debops
New Changelog and Copyright format
After finding http://keepachangelog.com/ I propose to over time switch the Changelog format to something more readable. I would also move the Copyright file contents into the Changelog, since the contributor information is closely related.
I've updated changelogs in two roles so far to test the new format, what do you think about the results?
New debops.php role, not yet released: https://github.com/debops/ansible-php/blob/master/CHANGES.rst
The debops.nodejs role: https://github.com/debops/ansible-nodejs/blob/master/CHANGES.rst
debops.nodejs changelog on the documentation site: http://docs.debops.org/en/latest/ansible/roles/ansible-nodejs/docs/changelog.html
http://keepachangelog.com/ looks nice! Dug a bit into the project and have a few minutes still to listen to the referenced podcast.
After checking out your examples I found a few things I would do differently:
- Don’t remove the copyright file. A copyright notice is the proper way to state that the program is Free Software/under the GPL. That is one of the cleaver things I like about the current docs format because the docs are a good place for the copyright notice (as I think).
- Consider referring to the latest stable version of Semantic Versioning e. g. v2.0.0. (Related to #103)
- Make version sections hyperlinks: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
Other than that I think it is a improvement we should implement.
I did that for debops.owncloud: https://github.com/ypid/ansible-owncloud/blob/rework-3/CHANGES.rst
Ad. 1: I removed the copyright file because after compiling all of the documentation in one place it just basically repeats over and over... I suppose that if it's important, I would move id to the root directory of the repository similar to how LICENSE file is placed and keep it in a simple text format. Not sure about the list of contributors - having it in the changelog makes maintenance easier and it's easy to look up the nicknames near each change if necessary.
Ad. 2: Agreed.
Ad. 3: reStructuredText provides that automatically. When you hover over section titles in your example changelog, you can see small icons which allow you to get a target link for that section. Just a bit of magic of the RST format. :-)
To 1: About the contributors section that is a good idea. Yes, it is important AFAIK: https://www.gnu.org/licenses/gpl-howto.html. I would leave this as is.
To 3: I know :wink: Have you clicked on the v0.2.0 in v0.2.0 - 2015-11-12 yet? Refer to: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md
Ad. 1: The GNU project suggests inclusion of the copyright notice in every source file... I would go with putting a COPYRIGHT file at the top of each repository in plaintext, with something like:
Copyright (C) 2015-2016 DebOps Project http://debops.org/
This file is part of DebOps.
DebOps is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3, as
published by the Free Software Foundation.
DebOps is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with DebOps. If not, see <http://www.gnu.org/licenses/>.
After that, as I understand it, this copyright would apply to all files in the repository, unless a different copyright is included in a file. For example, profile_tasks callback plugin is licensed under MIT License, which is included in the file itself. Do you think that this would be an acceptable solution?
Ad. 3: Well, that's neat but in the plaintext format it looks... well, not so neat:
`v0.2.0 <https://github.com/debops/ansible-owncloud/compare/v0.1.0...v0.2.0>`_ - 2015-11-12
-------------------------------------------------------------------------------------------
The links also strongly bond the project to GitHub, so it would be much harder to change the hosting domain if ever we decide to move.
Ad. 1: Sounds good. I think that should also do the trick. But I would suggest to stay with RST and maybe still include it in the docs.
Related to #132. Maybe @danstender can step in as dealing with licenses is an important part of packaging software. Maybe @danstender has also suggestions for the change log format. @danstender Awesame work by the way!
Ad. 3: Right. I have tried a bit to use hyperlink definitions and such but this was the most robust solution I did come up for RST. The strongly bond the project to GitHub is not an issue as it can be fixed by one global replace over all repos of the project (ref: https://github.com/debops/debops/issues/120#issuecomment-125267935). Automated edits will be needed for migrating to other hostings platforms anyway.
About the not so neat looking part in the source. Well, right, but what counts is the rendered version.
A way to easily see the changes on GitHub is definitely nice, but I don't like that it messes the readability of the text format. So, how about this compromise:
v0.2.0 - 2016-01-01
-------------------
`Compare changes <https://github.com/debops/debops/compare/v0.1.0...v0.2.0>`_
Changed
~~~~~~~
- Changed some stuff. [drybjed]
This should make headers human readable and provide nice links in the HTML version. I've prepared an example debops.pki Changelog to see the finished version. What do you think, @ypid?
As for inclusion of the COPYRIGHT file, it could be included similarly to how playbooks are included from an external file, perhaps in the docs/introduction.rst file?
A way to easily see the changes on GitHub is definitely nice, but I don't like that it messes the readability of the text format. So, how about this compromise
Sounds good. Lets go with that.
As for inclusion of the COPYRIGHT file, it could be included similarly to how playbooks are included from an external file, perhaps in the docs/introduction.rst file?
I would include it at the same position in the docs as currently done.
From @drybjed in https://github.com/debops/debops-policy/issues/9#issuecomment-236147715
Well, nice release notes are neat, but having to copy the changelog contents each time to the GitHub interface, not that interesting after a few times. I suppose that the git tags could have some more content in them besides the role name, but it's again duplication of data.
Adding a bit more infos to the git tags is a good idea. I would propose:
${Role_name_or_repo_name} vX.Y.Z
Changelog: https://docs.debops.org/en/latest/debops-policy/docs/changelog.html#debops-policy-v0-1-0-unreleased Changelog source: https://github.com/debops/debops-policy/blob/master/CHANGES.rst#debops-policy-v010---unreleased
I would not put the changelog in the git tags because then the changelog can not be edited afterwards (which might come in handy for fixing typos and improving rst/Sphinx stuff). Also to avoid redundancy as you said.
And who's going to have to update both links on every release and remember to paste all that in the tag description? :-) How about moving this to the API status page? Each role could have its own page with changelog embedded (I'm not sure about the RST->MD conversion for jekyll though) or a list of links that point to each tag compare page on GitHub, like the ones in the Changelog?
And who's going to have to update both links on every release and remember to paste all that in the tag description? :-)
According to our current policy, that would be you :) But there are only two URLs and you should be able to write a little script which preseeds/autogens the git tag message.
How about moving this to the API status page?
It is already available in the docs. We could include a API parameter like changelog_url which points to the docs.debops.org.
Hosting on debops.org status page
I am not sure what advantage that would have. debops.org is currently in rework a bit because you intended to move the wiki to debops.org.