1

Looking to automate our changelogs and release notes with conventional commits and Azure DevOps pipelines, and the process seems "simple" based on all of the documentation and videos I've consumed over the past few weeks. However, everything I've ran across shows teams making updates to their changelogs and/or release notes when PRs are approved and the CI process is finished, which seems like the right way to do it.

However, are there instances where these changelog or release notes generation doesn't happen until the changes in question have been sent to production?

David Coxsey
  • 95
  • 1
  • 7
  • 1
    I suggest you use git and log the changes with commit messages. Then you have the changes and the log of them neatly together. Cf. [Git Magic by Ben Lynn August 2007](http://www-cs-students.stanford.edu/~blynn/gitmagic/book.pdf) – hakre May 25 '23 at 16:08
  • Yeah, we're using git for our repos, but I think my main question is when it is appropriate to do the changelog update? When the PR is approved or when the item is deployed to production? – David Coxsey May 25 '23 at 18:25
  • Don't work with PRs, approve the change in CI (automated) and directly merge to trunk and automatically deploy to production. – hakre May 25 '23 at 21:19
  • What do you mean by not working with PRs? Are you referring to the actual process to generate the release notes or the overall approval of a dev's changes that need to be merged into the main branch? – David Coxsey May 30 '23 at 14:59
  • you push the changes and when the build is green, they automatically go into trunk and are deployed. if you want to keep up with the change-log, display the log of trunk. which requirements for release notes do you have? the approval should be well defined and directly automated. if you need approval by a person, consider to do pair programming instead of pull requests. – hakre May 30 '23 at 17:37
  • Change logs can be generated from semantic commit messages and don't necessarily have to ever be checked back in to the repo. About the only thing a build/release process should ever write into the repo are tags to associate release versions with the revision hash used to build the release and I always recommend maintaining that association in a separate database. The meta tag on the package version string is ideal if your packaging tool preserves those. – jwdonahue Jun 02 '23 at 21:21

1 Answers1

0

Maintaining a changelog in the repo does not scale well. In a multi-developer environment you will slow everybody down trying to resolve merge conflicts. For a small enough team, manually editing and committing the changelog for every change is doable, but I'd recommend moving away from that practice.

Automated changelog generation from commit messages/Id's, including work-item id's and titles, just prior to package generation is a very good approach. These changelogs do not need to be checked-in to revision control. You should preserve past changelogs in an immutable form somewhere outside of the source repo.

At the very least, a changelog should include commit hash Id's for all changes and the Id from which the release was built. Adding work item Id's and titles is even more useful.

Build meta in the version string is a good place to encode a reference to the changelog, if your package feeds/tools preserve that field (some do not).

I would recommend maintaining a separate database of references to build logs (age these out), builds (keep these) and the associated commit hash from which they were built and reference to the associated changelog. Such a system allows you to scale up, without hinderance, to parallel and distributed builds running across any set of branches being worked at any given time.

jwdonahue
  • 6,199
  • 2
  • 21
  • 43