Changelog guidelines?

[cognifloyd]

Is there a policy or a contributor guideline somewhere that says when to include changelog entries?

Right now, when to require a changelog entry feels arbitrary - based only on whichever maintainer ends up reviewing a PR.

If there is no policy or guideline, could we add one somewhere so that everyone can get on the same page about what constitutes something that should hit the Changelog?

[cognifloyd]

The only guidance I can find is the deprecation policy https://docs.stackstorm.com/development/index.html#deprecation-policy (added emphasis on Changelog)

This is an example of a typical deprecation timeline:

• 2.0: New configuration format introduced. Documentation updated to refer to both old and new versions, with information on migration.

• 2.1: WARNING logs generated on use of old-style configuration, e.g. at time of pack registration. Changelog to include note in “Deprecated” section. Documentation should focus on new style, with reference information on migration. Users can keep using the older configuration.

• 2.2: Continue with previous WARNING logs. Users may still keep the older configuration.

• 2.3: Fatal ERROR logs generated on use of old-style configuration. Documentation should only refer to new style. Changelog entry added in “Removed” section. At this point the feature is no longer supported, and users must migrate.

[blag]

We don't have a perfectly consistent policy, sometimes I reviewers forget to require that and it has to be added later. Some people want every PR to have its own changelog entry, and only one changelog entry.

I take a more relaxed approach. The changelog is meant to be for humans, and specifically for humans when they are figuring out if/when they can upgrade their StackStorm instances. So every change that modifies code that a user will run (eg: "production code") should get a changelog entry.

That also means that parts of the project that will not change any production code don't need changelog entries. This includes things like CI configuration changes (GitHub Actions, CircleCI, Travis CI, etc.) and anything that only modifies test code (so if a PR modifies production code and test code, it will still need a changelog entry because it touched production code).

Within StackStorm Exchange, one of the reasons that I leave out a version bump and a changelog entry until the end of the PR is because there's a race condition in that - somebody else's PR might bump to the same version that I bumped to, or worse, they bump a major version where my PR only bumps a minor version. And having the last commit of a PR bump the version and update the changelog also makes it slightly more easier to figure out the last commit of a multi-commit PR when you are digging through git history.

[cognifloyd]

So, that suggests any contributor guidelines (or tips?) should suggest slightly different workflow for exchange packs vs core st2. The st2 installers are another category that might need separate treatment.

[blag]

The pack versions are really only a problem in Exchange, since the version number doesn't get bumped in the course of normal development for core ST2, and having non-continuous version numbers in Exchange isn't handled gracefully/correctly by our deployment automation (while this is technically an issue we can solve, I don't think it's a big enough deal in practice to worry about).

However, it's not uncommon for the changelog in core ST2 to be a source of merge conflict. Typically if you have a long running PR that is adding a feature or changing something, if somebody else has a smaller PR that adds something or changes something and their entries go in the same list, and theirs gets committed first, then Git doesn't know which entry to take (it should take both). In ST2 Exchange, each PR pretty much always entails a new version, so merge conflicts in the changelog are less common.

So you're correct - it might be good to tweak the pull request template for ST2 (and add PR templates for ST2 Exchange) that gives contributors a heads up about what to expect regarding versioning and changelog entries.

I can't accurately comment on how we version and control the changelog for our installers, since I don't really contribute there at all. But if it makes sense to have slightly different guidelines for those as well, then I'm in favor of making that explicit. 👍

[cognifloyd]

Other projects have separate changelogs per version. Others (like ansible) have one changelog snippet for each PR that needs to add one. During release, all those snippets get combined into one changelog. This has the benefit of sidestepping all the annoyingly pointless merge conflicts.

[arm4b]

https://keepachangelog.com/en/1.0.0/ and https://github.com/olivierlacan/keep-a-changelog looks useful.

I think there are some nice fundamental questions and answers:

Why keep a changelog?

To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

Who needs a changelog?

People do. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how.

[cognifloyd]

Cool. So now we need a good definition of "notable".