Open jkrems opened 9 years ago
jkrems
commented
9 years ago I'm not sure if it's relevant to npub, but I like the "Known Issues" section io.js has. E.g. calling out things that are known not to work. But as I said - not sure if npub should have opinions on such details.
EndangeredMassa
commented
9 years ago I love this. I would like to include the dates. Integrating tags in the generation makes a lot of sense, as well.
How about the following as an example?
# Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).
## [Unreleased](COMPARE_LINK_TO_MASTER)
- [#123](SOME_PR) some pending changes
- [#124](SOME_PR) that will be released in the next version
## [1.2.3](COMPARE_LINK) - YYYY-MM-DD
Any general description of this version
can go here.
- [#125](SOME_PR) some additions
- [#126](SOME_PR) that would require a minor version bump
### Bug Fixes
- [#127](SOME_PR) some changes that fix bugs
- [#128](SOME_PR) and would require a patch version bump
### Breaking Changes
- [#129](SOME_PR) some backwards-compatibility changes
- [#130](SOME_PR) that require a major version bumpWhen we integrate GitHub access, the changelog would be generated based on this example. Tags will determine where items show up. Maybe this doesn't leave a place for the unreleased section, which is fine with me.
jkrems
commented
9 years ago I'm not a fan of "Unreleased", it just makes cherry-picking/back-porting features across branches harder. The changes in a commit are for actual changes, house keeping should go into commit messages etc.. Maybe not a problem for a very small library without support for older versions, but definitely for something where multiple major versions have to be supported.
Also since npub can read the PR headings from the merge commit messages, there's no advantage of having "Unreleased". If your release cadence is so slow that there are a bunch of interesting features merged but not yet released, I don't think the fix is not to add an "Unreleased" section to your change log.
In terms of ordering, I'd switch "Breaking" and "Bug Fix". Other than that: Looks nice! Maybe add back the author?
- [#125](SOME_PR) some additions - [@quinn](USER)
- [#126](SOME_PR) that would require a minor version bump - [@sam](USER)Agreed.
# Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).
## [1.2.3](COMPARE_LINK) - YYYY-MM-DD
Any general description of this version
can go here.
- [#125](SOME_PR) some additions - [user](USER_LINK)
- [#126](SOME_PR) that would require a minor version bump - [user](USER_LINK)
### Breaking Changes
- [#129](SOME_PR) some backwards-compatibility changes - [user](USER_LINK)
- [#130](SOME_PR) that require a major version bump - [user](USER_LINK)
### Bug Fixes
- [#127](SOME_PR) some changes that fix bugs - [user](USER_LINK)
- [#128](SOME_PR) and would require a patch version bump - [user](USER_LINK)Beautiful! :+1:
While it's not a hard standard, "Keep a Changelog" has some interesting improvements over the current change log format:
[1.0.3]+ link to/compare/x...y, it's easy for people to get to the exact diff from the last version"Changed", "Added", etc. don't seem helpful, I think "major/minor/patch" would be more meaningful (assuming semver):
semver-minor/no category, just "normal" changessemver-major/"Breaking Changes"semver-patch/"Bug fixes""Deprecat*" or "Security" should always appear in the line item itself, an additional heading seems overcomplicated. Removal is a breaking change, no need for a dedicated heading.
If a project adopts io.js style semver tags, those headings could actually be pre-filled from PR information.
And obviously we'd want nice PR links with full URLs, something that page doesn't mention.
References