Skip to content

Automated Change Log

Jump to bottom
Edgar edited this page Dec 14, 2023 · 6 revisions

Introduction

Periodically, we create releases of updated workspaces, by publishing new package versions in https://www.npmjs.com/org/sjcrh. These packages are used in portals and containers.

Release notes and/or change logs help inform customers of various feature enhancements and bug fixes. These release notes can also inform release test plans.

Automation Goals

  • encourage the tracking and generation of release notes at the time that features or fixes are coded
  • minimize merge conflicts as related to editing the same release.txt or CHANGELOG.md file in multiple active branches
  • avoid having to manually scan the commit history for relevant release notes
  • maintain a consistent document structure for tracking change logs

Automation Stages

The automation is coded in multiple places of the development workflow.

Pre-commit

You can use one of the following methods to create entries in release.txt.

Edit release.txt directly

New notes can be entered manually into release.txt in a strict format, using supported section heading such as Features, Fixes, DevOps, and others.

Features
- something new

Fixes
- a bug fix for some issue

TODO: Instead of the strict format above, expect the simple unsectioned line entries with the short keywords described in the commit method below, like feat: , fix: , etc.

Use commit keywords

However, there is also automation to support commit keywords, such as feat: and fix: (note the space after the colon). These keywords may be used at the beginning of commit message line(s). This will put all detected commit lines under the corresponding section in release.txt. This automation is coded in

  • build/setReleaseText.js, as called by the next code below
  • utils/hooks/commit-msg.sh: must call npm run sethooks if you don't see .git/hooks/commit-msg or ../.git/modules/hooks/commit-msg if proteinpaint is a submodule

TODO: Create a release.txt for each workspace in our monorepo. When multiple workspaces are affected by a change, the same release note will be copied to the release.txt of all affected workspace.

Post-PR merge

Update CHANGELOG.md, empty release.txt

When a PR is approved and merged, the Merge Change Log workflow will detect if there are release.txt entries. If there are, those entries will be added to the Unreleased section of CHANGELOG.md. This automation is coded in:

  • build/changeLogGenerator.js, as called by the next code below
  • github/workflows/CI-merge-change-log.yml

During release

Change the Unreleased title to the new version number

In the Create Release workflow, the new version number will replace the Unreleased section title. Before triggering that workflow, the Unreleased section of the CHANGELOG.md should be reviewed and edited for clarity and to fix typographical or grammatical errors. This automation is coded in:

  • build/ci-version-update.sh, as called by the next code below
  • github/workflows/CI-create-release.yml
Clone this wiki locally