keep-a-changelog
keep-a-changelog copied to clipboard
olivierlacan
The tool
There were already some suggestions about a "tool".
I think they should be concentrated in one issue concerning the tool specifically.
What should it do?
- Check your changelog for syntax errors
- Be able to convert your changelog files from distros, etc .. into this format (plugin-able)
- This tool should use some "template" - a standard that would define the changelog syntax for the checking and conversion
- Should maybe contain some dictionary with key-words, like breaks, yanked to suggest instead adding [BREAKS], [YANKED] tag or similar
- Export public version of this document without [internal] tagged lines.
I can cook something up in Python, but as this is not my own project, I don't want to impose my preferences on anyone :)
However this tool should be part of this project, something like Syncthing - they also have reference implementation for their protocol, and it seems like a good idea.
On the subject of filtering [INTERNAL] comments, here's a very naive solution I spiked on several months back: https://gist.github.com/olivierlacan/af246b98101a7cf33360
One thing that might be nice is if the tool supported building annotated git tags based on the changelog. So, if we use this project's changelog as an example, it could take this:
# Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).
## [Unreleased][unreleased]
## [0.0.7] - 2015-02-16
### Added
- Link, and make it obvious that date format is ISO 8601
### Changed
- Clarified the section on "Is there a standard change log format?"
### Fixed
- Fix Markdown links to tag comparison URL with footnote-style links.
## [0.0.6] - 2014-12-12
### Added
- README section on "yanked" releases.
[snip]
and create an annotated git tag v0.0.7 with contents something like this:
# Version 0.0.7 release
### Added
- Link, and make it obvious that date format is ISO 8601
### Changed
- Clarified the section on "Is there a standard change log format?"
### Fixed
- Fix Markdown links to tag comparison URL with footnote-style links.
I have a Ruby script that does this for a different changelog format that I could modify slightly to work with the convention here.
@elyscape Good idea although using this project as an example remember that annotated git tag messages work very much like commits so it's best to keep the first line as a condensed summary of the release and not a repeat of the information already encoded in the tag itself (v0.0.7). You can see an example of how that work here: https://github.com/olivierlacan/keep-a-changelog/tags
Expand the [...] links on each tag and you will see the messages (which for now only include the condensed summary I mentioned).
Assuming the git tags were properly created on the actual release date of the version or backdated using the git committer date variable (GIT_COMMITTER_DATE="2015-02-16" git tag -s v0.0.7) we can also extract the proper release date from them.
My script does backdate to the time of the tagged commit, but I could also modify it to also prompt for a version name so it would output something like:
# Acknowledge GNU change log style, point to ISO 8601, clean links
### Added
- Link, and make it obvious that date format is ISO 8601
### Changed
- Clarified the section on "Is there a standard change log format?"
### Fixed
- Fix Markdown links to tag comparison URL with footnote-style links.
@elyscape I couldn't remember why I didn't put the categories from the release in the git tag yesterday, and then today I remembered why:
v0.0.8 Fix factual error on date formats, typos, and erroneous links.
- Update year to match in every README example.
- Reluctantly stop making fun of Brits only, since most of the world
writes dates in a strange way.
- Fix typos in recent README changes.
- Update outdated unreleased diff link.
A # is a comment in any git message. Unless you somehow change the default comment character with the core.commentchar setting (since git 1.8.2, February 2013). It's also possible to avoid that issue while creating the message with --cleanup=whitespace. That works on both git commit and git tag.
You will then have to remember to remove the default comment that git adds (which remain prepended with a #, oddly).
Looks good when done right though:
The only issue at this point is that the Markdown heading level is now improper (heading 3) if there is no heading 1 and heading 2 to accompany it, so that should probably change.
That's all pretty simple to handle inside a script. As for the default comment, my script writes the tag message to a file and then feeds it to git with git tag -F filename, so that's not a concern in the first place.
The only issue at this point is that the Markdown heading level is now improper (heading 3) if there is no heading 1 and heading 2 to accompany it, so that should probably change.
Does that matter much, though? I'm not aware of a requirement that H3s be preceded by H2s and/or H1s.
https://github.com/skywinder/github-changelog-generator https://github.com/skywinder/Github-Changelog-Generator/wiki/Alternatives
For the people interested, we've been working on a tool regarding changelogs the past couple months (based on this spec) It is still in beta but would love to hear your thoughts on it:
http://beta.changehub.io/
The marketing bit is still being worked on. But it first of all parses Github releases, and secondly it parses pull requests descriptions following the keepachangelog.com format to generate the unreleased changelog notes.
Also I'm aware it doesn't read a changelog.md file, but there are plans to support this in the near future.
It seems that it is now in public beta and the new URL is http://changehub.io/.
@bramdevries Signing up doesn't work as there is a 404 when pushing "Keep me updated".
One thing that might be nice is if the tool supported building annotated git tags based on the changelog. So, if we use this project's changelog as an example, it could take this:
# Change Log All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/). ## [Unreleased][unreleased] ## [0.0.7] - 2015-02-16 ### Added - Link, and make it obvious that date format is ISO 8601 ### Changed - Clarified the section on "Is there a standard change log format?" ### Fixed - Fix Markdown links to tag comparison URL with footnote-style links. ## [0.0.6] - 2014-12-12 ### Added - README section on "yanked" releases. [snip]and create an annotated git tag
v0.0.7with contents something like this:# Version 0.0.7 release ### Added - Link, and make it obvious that date format is ISO 8601 ### Changed - Clarified the section on "Is there a standard change log format?" ### Fixed - Fix Markdown links to tag comparison URL with footnote-style links.
@elyscape I wish I had read this:
I have a Ruby script that does this for a different changelog format that I could modify slightly to work with the convention here.
before I wrote https://github.com/ianfixes/keepachangelog_manager_gem
It does the thing you suggest, although for the changelog file itself.
