Add manpage #326
Add manpage #326
Conversation
Codecov Report
@@ Coverage Diff @@
## master #326 +/- ##
=======================================
Coverage 96.78% 96.78%
=======================================
Files 20 20
Lines 1183 1183
Branches 106 106
=======================================
Hits 1145 1145
Misses 20 20
Partials 18 18 Continue to review full report at Codecov.
|
|
Thanks @sergiosacj for the man page. Much appreciated. To me it looks a great start for towncrier documentation. I guess that later it can be converted to Sphinx manpage builder to make it easier to update it and the current version is good for now. I will leave @altendky to take the final decision as he is the current maintainer The failed CI jobs are not related to this PR...so they can be ignored. Thanks again! |
|
Thanks for the contribution. Like @adiroiban I thought (albeit briefly) about how this can be generated. My first thought was generating from the existing click |
|
This contribution appears to use a different license from Towncrier's — GPLv3 vs. MIT. Do we have a Twisted policy on this? |
|
Good catch. I would think that Debian could relicense as GPL. I wouldn't expect to put a GPL license into this repository though. |
|
The reason I did it this way is because the maintainer of the Debian towncrier package has chosen to use GPLv3 in the package. As the manpage is part of the package, I did the same. I understand the trouble that this causes, will this PR be closed then? |
|
@sergiosacj would you mind submitting this PR under the MIT license? I am not a legal expert.. The way I understand GPL is that if we accept the man page under GPL, BSD distros would not be able to use it as is. If you are the author of the work there should be no problem using the man page in Debian under GPL but send it upstream as MIT. Thanks! |
|
@sergiosacj sorry, I should have used more words. I agree with @adiroiban. I did not mean to dismiss your contribution over the license. I just meant that I would expect the licenses expressed in this repository to match between the overall repo and the manpage. On the side, while it is my understanding that Debian could relicense an MIT project as GPL... it seems pretty odd and misrepresentative to do so. But, that's no matter when reviewing this PR. On to the actual content... The first layer I see is that while the subcommands are listed, the options are presented as global rather than subcommand specific. Presently listed in the manpage:
This does not exactly agree with any subcommand, nor is it an overall comprehensive list combined together. Maybe it matches 19.9rc1 or something? It looks like git takes the same approach as Complete actual `--help`$ venv/bin/towncrier --help
Usage: towncrier [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
build*
check
create$ venv/bin/towncrier build --help
Usage: towncrier build [OPTIONS]
Options:
--draft Render the news fragments, don't write to files, don't check
versions.
--config TEXT Configuration file name.
--dir TEXT
--name TEXT
--version TEXT Render the news fragments using given version.
--date TEXT
--yes Do not ask for confirmation to remove news fragments.
--help Show this message and exit.$ venv/bin/towncrier check --help
Usage: towncrier check [OPTIONS]
Options:
--compare-with TEXT
--dir TEXT
--config TEXT
--help Show this message and exit.$ venv/bin/towncrier create --help
Usage: towncrier create [OPTIONS] FILENAME
Options:
--dir TEXT
--config TEXT
--edit / --no-edit Open an editor for writing the newsfragment content.
--help Show this message and exit.@sergiosacj, to make sure I understand the situation. Does getting this merged quickly or not have much effect on your work on the Debian side? What version of towncrier are you releasing? For what it's worth, I do appreciate your effort to bring this work here. I agree that the project itself ought to at least enable generation of the needed forms of documentation. manpages are pretty general so it does seem reasonable to try to provide that here. Just a matter of finding time for the work... |
|
@sergiosacj My understanding is that if you are the author of the manpage, you are allowed to choose a license every time you distribute it. It's OK to give it to Debian under a GPL license and to Twisted under an MIT license. At least, that's how American copyright law works; I assume that it's the same in Brazil (since Brazil is a member of the usual international copyright conventions). Unless you have a preference for another license, I think it would be easiest for end-users if you license it under the same terms as other Towncrier code/documentation. @altendky It's not uncommon for the manpage to simply list each subcommand invocation and its options in the SUMMARY section, e.g.: |
|
Thanks @adiroiban, @altendky and @wiml for the explanations, they helped me a lot. I will change the license as suggested. In my understanding, the current maintainer of the package did not relicense the software, it is adding a specific license for the material produced in Debian. I agree that placing a license other than upstream only makes it difficult to submit changes and it's not a good practice, but I don't think it is misrepresentative. On to the actual content, as I am not a towncrier user, it was very difficult to document the commands. That's why I wrote on that style. I'll try to spend more time reading the code to improve the manual. Any information about how the software works is welcome. I'm not in a hurry, in fact, the way I wrote my first message made the wrong impression, sorry about that. My goal with this contribution is to increase the quality of the package and close some bugs, my work does not influence the existence of the package. As I am not the maintainer of the package, I also do not make decisions. Even though I prefer to generate the manpage, it was the maintainer's preference to have the manual written in groff. The version of towncrier that is being released is 19.2.0. As we are in the freezing period, towncrier will not be available on Debian Bullseye. At least, not for now. |
|
Alrighty. So you prefer a generated man page, and so do I. There's an effort over in #89 to create some Sphinx docs and @adiroiban mentioned a Sphinx-related manpage generation tool. I mentioned a Click-related manpage generation tool. I'm not sure what the appropriate path is. I also wasn't expecting to be prioritizing the documentation rework at this point as I am failing to even get a release out... and that release doesn't even include some of the original features that made me start my work here. Anyways, @sergiosacj, are you interested in taking a look and giving a quick explanation of the relevant tools and how we might reduce repetition across Click, possible Sphinx documentation, and a manpage? Maybe we can write prose in a normal Sphinx setup and have that go into the manpage and then have brief option explanations written as-is in the Click command and option definitions but have them generated into the Sphinx output plus manpages... Seems like the sort of thing that might 'just work' but also might 'never be able to be made to work'. I dunno. |
|
I really like your idea, but I don't think I have time to work on it. For now, I will try to improve the quality of this manpage so that it can help a more elaborated documentation in the future. If I make any promises beyond that, it is very likely that I will not be able to keep it. I'll try to start small. |
|
Thanks for the licence update. I think the only blocker for this PR is making sure that it documents towncrier latest dev version. Sphinx or click man page generators should not be a blocker. I don't see the By reading both I think that is ok to list all shared command line option only once.... but maybe in a "Shared options" paragraph. For easy refefence. below is the --help output from master |
It was written for the Debian GNU/Linux system but may be used by others.
|
@adiroiban Instead of creating a "Shared options" paragraph, I defined each option within the respective command. It allowed me to customize the descriptions, just like "--help" does. Is it okay to keep it like this? |
|
Adi initially deferred to me but I have since delegated back to them on this one. |
|
Thank you for beginning this merge request.
That's not permitted, as Sergio does not have permission to re-license the manual page under MIT conditions. The manual page is distributed under conditions of the GPLv3-or-later license grant.
That's not true; BSD distributions include a lot of works that are licensed under GPLv3-or-later license grant, and many different ones also. The Town Crier project has permission (under the GPLv3-or-later license grant) to redistribute this manual page, and all recipients have the same license grant from the copyright holder. So BSD distributions (and anyone else) has those full permissions also.
Fortunately, that's not permitted; the license permits changes, but those changes can be redistributed only if the GPLv3 conditions are met. You might be thinking that the MIT license on other parts of Town Crier are relevant here? The parts of Town Crier covered by the MIT license are not linked to the manual page (and vice versa) in a way that would violate the license on either of them. So the fact they're under different license grants is not a problem; the licenses allow any recipient to freely modify and redistribute the work, even together in the same Town Crier project or a different project. |
If the work is derived from the original, it will need to be licensed under GPLv3. I granted that license to anyone and you're free to use it under those conditions.
Thank you, that's accurate. Yes, it is normal for a non-trivial project to have free software under various licenses collected together. Provided they all allow recipients of the software to exercise all software freedoms needed, there should not be a problem. One thing that is needed, of course, is to be clear what license is granted in what works; the description in the project will need to say who are the copyright holders in what parts, what exact parts are MIT-licensed, what exact parts are GPLv3-licensed, etc. and the license text needs to be in the project so recipients can get it in the same place no matter when they received the project files.
I'm also happy to receive improvements and just update the original directly. I will probably make a branch in my own repo for this, and make that available. Would that be easier? |
I believe the manual page now at branch wip/issue/384/manual-page correctly documents the |
|
Thanks for the feedback. I think that instead of having a manpage in "upstream" towncrier, we should look at improving the current This should help with users on any OS. There is https://github.com/click-contrib/click-man to generate the man format. I think that is ok for distribution to create their separate manpages. There is also an overlap / duplication between the manpages and the "official" RST base documentation. I will use the help text from the manpage from this PR to include it into the CLI output. Right now the CLI The other man-page is GPL, so I will not use it so that we can keep the towncrier as MIT. |
|
so... as a first step. we should make sure that our CLI and "official" documentation have enough information to benefit all users, not only Debian or derivative distros. Disclaimer: I am an Ubuntu user. |
|
so, the plan is to fix this via #294 That is, update the CLI help messages to be as good as the proposed man pages. Use This should reduce code duplication and should help make sure the man pages are yn sync with the released version. |
I am closing some bugs in Debian to help add towncrier to the project.
One of them was related to the creation of a manpage. So, following Debian Developer's Reference, I am bringing it upstream because I believe it may be an useful addition.