Release process is not well described

[oskarpearson]

The release process of this gem is not well described.

If #91 works as expected, I suggest adding a RELEASE_PROCESS.md file as below

Cutting a new release

When creating a PR to master you should include a text fragment like this in the PR description

# Changelog

## Unreleased

* [ADDED|CHANGED] One line description of a change
* [ADDED|CHANGED] Second description of another change

On merging to master, you should set one of the following labels:

• release-patch - to release a new patch version (eg: 5.0.1 or 6.1.1)
• release-minor - to release a new minor version (eg: 5.1 or 5.2 or 6.1)
• release-major - to release a new major version (eg: 5.0 or 6.0)

Underlying Code

Understanding the Release Process in release.yml

This document explains how the release.yml workflow updates the CHANGELOG.md file during a release.

Breakdown of the Key Code Block

The following section of release.yml handles extracting the latest release notes from a pull request and updating CHANGELOG.md accordingly.

echo "${{ github.event.pull_request.body }}" | csplit -s - "/##/"
echo "# Changelog
## ${{ env.VERSION }}
" >> CHANGELOG.tmp
grep "^*" xx01 >> CHANGELOG.tmp
grep -v "^# " CHANGELOG.md >> CHANGELOG.tmp
cp CHANGELOG.tmp CHANGELOG.md

Extract the Changelog Entry from the PR Body

echo "${{ github.event.pull_request.body }}" | csplit -s - "/##/"

• Extracts the pull request body.
• Splits it at the first occurrence of ## (indicating a version header in Markdown).
• Stores the extracted sections into files xx00, xx01, etc.
• The file xx01 contains the new changelog entry from the PR.

Create a New Changelog File

echo "# Changelog

${{ env.VERSION }}

" >> CHANGELOG.tmp

• Appends a new changelog section for the upcoming release.

• ${{ env.VERSION }} contains the version number (e.g., 4.1.0).

• Results in an initial structure like:

  Changelog

  4.1.0

Extract the Changelog Content

grep "^*" xx01 >> CHANGELOG.tmp

• Looks for lines in xx01 that start with * (bullet points for changes).
• Appends them under the new version heading.
• Ensures only relevant change entries are included.

Append the Existing Changelog (Without H1 Headers)

grep -v "^# " CHANGELOG.md >> CHANGELOG.tmp

• Removes any existing # Changelog H1 header from CHANGELOG.md.
• Keeps all ## X.Y.Z version headers and their contents.
• Ensures that only one top-level # Changelog title exists.
• Appends the remaining content to CHANGELOG.tmp.

Overwrite CHANGELOG.md with the Updated Version

cp CHANGELOG.tmp CHANGELOG.md

• Replaces CHANGELOG.md with CHANGELOG.tmp.
• Ensures the new release is added at the top, keeping all previous release notes intact.

Summary

1. Extracts the changelog section from the PR description.
2. Creates a new CHANGELOG.tmp with the new version number.
3. Adds the list of changes from the PR description.
4. Removes any existing H1 (# Changelog) header from CHANGELOG.md and appends the rest.
5. Overwrites CHANGELOG.md with the updated version.

This ensures that the latest release notes appear at the top, and all previous release notes remain intact without duplicate headers.

This automated approach prevents manual errors in updating the changelog and streamlines the release process for maintainers.