I just stumbled upon this site <http://keepachangelog.com/#> for the first time and it put some of the thoughts I've had more explicitly and in more refined arguments. Some portions that stood out to me:
> - Each version should: > - List its release date in the above format. > - Group changes to describe their impact on the project, as follows: > - `Added` for new features. > - `Changed` for changes in existing functionality. > - `Deprecated` for once-stable features removed in upcoming releases. > - `Removed` for deprecated features removed in this release. > - `Fixed` for any bug fixes. > - `Security` to invite users to upgrade in case of vulnerabilities. > > ... > ### What makes unicorns cry? > Alright…let’s get into it. > > > - **Dumping a diff of commit logs.** Just don’t do that, you’re helping > nobody. > > ... > ### Why can’t people just use a `git log` diff? > > Because log diffs are full of noise — by nature. They could not make a > suitable > change log even in a hypothetical project run by perfect humans who never make > typos, never forget to commit new files, never miss any part of a refactoring. > The purpose of a commit is to document one atomic step in the process by which > the code evolves from one state to another. The purpose of a change log is to > document the noteworthy differences between these states. > > For people who aren't closely watching mezzanine development, the question "How do I upgrade to the latest version?" is not a straightforward one to answer. In the past folks have developed upgrade guides in the process of upgrading their own sites, but this is inherently haphazard since it only catches the features those individuals use and tested. There are two ways to keep a good changelog that I'm aware of: (1) enforce a strict commit message format and generate the changelog, (2) add a PR template with a task list including an item like "noted any breaking changes in the CHANGELOG" and maintain the changelog manually. Enforcement of either of these strategies may very well be more administrative hassle than it's worth. I don't have any actionable suggestions for mezzanine. I think we could keep a more useful changelog with time and effort, but I'm not sure it's worth it as long as new features are documented, deprecated features throw an appropriate warning, and we keep the project template and project example (drum) up to date. After all, most of the breaking changes are in django itself and we can't possibly duplicate the effort of tracking those. -- You received this message because you are subscribed to the Google Groups "Mezzanine Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
