search

ably / engineering

Ably's new home for engineering guidance, including content previously served from Confluence at engineering.ably.com.
https://engineering.ably.com/
Apache License 2.0
2 stars 6 forks source link

Change Log Process #17

Open QuintinWillison opened 2 years ago

QuintinWillison commented 2 years ago

In this PR comment I referred to a possible alternative to the way that we build our change logs for releases:

This is a good example of a change where we need to 'remember' (collectively) to ensure this is highlighted as a (potentially breaking?) change to runtime behaviour. Impacts:

  • It should appear in changelog as such for next release
  • Next release should perhaps have more than a patch revision bump (I know we're planning to make this part of a minor bump for next release, perhaps)

the basic mechanism was that when a change was made that was changelog-worthy for the next release then the changelog was modified as an atomic part of that change (i.e. within the same PR). I like that, a lot. We would need to define a standard for how we do this as a team

That is, our CHANGELOG.md would become a first class citizen in the development process. We would have a 'running tab' for the 'latest' (HEAD of main - default - branch) at the top, and then when we did a release PR the engineer working on that would curate and mould it into something that's ready to present for the that release.

QuintinWillison commented 2 years ago

Scope of work done under this issue should also include this internal Slack comment from @mattheworiordan:

Can we please write up a wiki entry on what the process is for SDK updates and public changelog and library changelog?

QuintinWillison commented 2 years ago

Internal Confluence pages on this topic:

There is probably value in bringing all this information into open source, within this repository.

QuintinWillison commented 2 years ago

We also need to define what things are 'change log worthy' and which things should not be added because they contribute 'noise' from the SDK-user / App-developer perspective. So, for example, the 'skipped test' entries in this change log commit don't add any value to SDK users who are going to be looking at the change log in order to discover things that might affect their application code.

QuintinWillison commented 1 year ago

We also need to consider the situation where we're releasing a version that's coming out of pre-release. This means that the changelog will have entries for each pre-release, yet we should probably (?) create a changelog entry for this new non-pre-release that summarises changes all the way back to the previous non-pre-release. e.g.:

Version Changelog Entry Scope
1.0.0
1.1.0-rc.1 From 1.0.0 to 1.1.0-rc.1
1.1.0-rc.2 From 1.1.0-rc.1 to 1.1.0-rc.2
1.1.0 From 1.0.0 to 1.1.0