Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add "Unreleased" section to the changelog #1809

Merged
merged 7 commits into from
Feb 2, 2016

Conversation

mehlah
Copy link
Member

@mehlah mehlah commented Dec 30, 2015

I'm writing a changelog in preparation for the next 1.0.0 release. (issue #1667)
I dumped the commit log (~300 commits) then worked it out commit by commit to keep only relevant ones and match the previous changelog format.
As you can see I still have a couple PRs to process before finishing it.
I'll go through it another time to make the sentences better with clarifications, double check breaking changes and reorder some items.

Am I on the right track? Do you have any feedbacks to make it better?

I tried to be consistent with what have been done before but I think we can make it better by:

  • Renaming History.md ~> Changelog.md, which is more conventional. (note that it was named Changelog before but renamed to History.txt by 41e951a)
  • Link to PRs or issues when is relevant for more details
  • Group changes in sections "Added", "Fixed", "Deprecated", ...
  • Maintain an "Unreleased" section and update it regularly (ideally for each PR merged) to avoid writing the changelog for a whole year of work and minimize the effort required for new releases.

Any thoughts on this?

@thomasfedb
Copy link
Contributor

I'd suggest CHANGELOG.md rather than Changelog.md in like with the README.md and CONTRIBUTING.md files we have. Arguably we should move CONTRIBUTING.md into the wiki...

@tmaier
Copy link
Contributor

tmaier commented Jan 2, 2016

I like the change log format defined at http://keepachangelog.com.

It uses, like you do "added", "fixed" and "deprecated", but groups them. I find good to get a better understanding what changed without using CMD+F to highlight all deprecated/removed things

@thomasfedb
Copy link
Contributor

That's a nice format @tmaier, I like it too.

I like the header also:

# Change Log
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).

I feel that we should definitely look to adopt SemVer when we release 1.0.0.

@thomasfedb
Copy link
Contributor

When complete this will resolve #1667.

@mehlah
Copy link
Member Author

mehlah commented Feb 2, 2016

@thomasfedb I updated the changelog 📝 based on your feedbacks and some of my suggestions above.
Please let me now if this looks good for you.

@mehlah mehlah changed the title WIP Add "Unreleased" section to the changelog Add "Unreleased" section to the changelog Feb 2, 2016
@thomasfedb
Copy link
Contributor

That's looking fantastic @mehlah, although I'm inclined to suggest that we should include as much history as possible - although the 0.10.0 cut-off may in fact be reasonable.

The only other thing missing might be issue/PR references. What do you think?

@mehlah
Copy link
Member Author

mehlah commented Feb 2, 2016

@thomasfedb

The only other thing missing might be issue/PR references. What do you think?

Booya! ded0237

thomasfedb added a commit that referenced this pull request Feb 2, 2016
Add a modern CHANGELOG.md to project
@thomasfedb thomasfedb merged commit fd9fc91 into carrierwaveuploader:master Feb 2, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants