Skip to content

RELEASES.md

Latest commit

 

History

History
181 lines (128 loc) · 5.63 KB

RELEASES.md

File metadata and controls

181 lines (128 loc) · 5.63 KB

Release Procedure for action-handle-fix-commit

This document is the authoritative checklist for publishing a new version of this action. Follow every step in order. The release is not complete until all steps are checked off.

Background: how releases work

Tags and versions

This repository uses plain integer major-version tags: v1, v2, v3, ... There are no patch or minor releases; every published change is a new major version.

What dependabot reads

When dependabot opens a PR in a consumer repository (e.g. phlex) to update a pin from @SHA # v1 to @SHA # v2, its PR description contains:

  • Release notes: the body of the GitHub Release whose tag_name is v2. Written at release-creation time (step 6 below).
  • Changelog: the ## v2 section extracted from CHANGELOG.md at the tip of main. Written in step 2 below.

Both sources must be present and accurate for the dependabot PR to be useful to reviewers.

Pre-release checklist

Before tagging, verify:

  • All CI checks on main are green.
  • action.yaml reflects the intended interface (all inputs/outputs documented).
  • All uses: references in action.yaml are SHA-pinned.
  • README.md usage example is up to date (inputs shown, SHA will be updated post-tag in step 8).

Release checklist

Step 1 — Determine the new version number

Increment the current latest version by 1. Example: if v2 is the latest tag, the new version is v3.

NEXT_VERSION=v3     # replace with actual next version
TODAY=$(date +%Y-%m-%d)

Step 2 — Add a changelog section to CHANGELOG.md on main

Prepend a new section immediately after the # Changelog heading:

## vN --- YYYY-MM-DD

### What's Changed

- <bullet describing each user-visible change; link PRs as (#N)>

### Breaking Changes

- <list breaking changes, or omit this subsection if none>

Commit and push directly to main (or via a PR if branch protection is enabled):

git add CHANGELOG.md
git commit -m "docs: changelog for ${NEXT_VERSION}"
git push origin main

Step 3 — Verify CHANGELOG.md heading format

Dependabot's changelog extractor requires the version token to appear in the ## heading. Run this sanity check:

grep "^## ${NEXT_VERSION}" CHANGELOG.md \
  || { echo "ERROR: ${NEXT_VERSION} section missing from CHANGELOG.md"; exit 1; }

Step 4 — Create an annotated tag

git fetch origin main
git checkout main
git pull --ff-only origin main
git tag "${NEXT_VERSION}" -m "${NEXT_VERSION} - <one-line summary>"

Do not use a lightweight tag; annotated tags carry authorship and message metadata and produce cleaner release output.

Step 5 — Push the tag

git push origin "${NEXT_VERSION}"

Step 6 — Create the GitHub Release

Use GitHub's autogenerated notes as a starting point:

gh release create "${NEXT_VERSION}" \
  --title "${NEXT_VERSION} - <one-line summary>" \
  --generate-notes \
  --repo Framework-R-D/action-handle-fix-commit

--generate-notes uses .github/release.yaml to categorize merged PRs since the previous tag. Review and augment the generated body:

  • Ensure the "Breaking Changes" section is accurate (or absent if none).
  • Add a one-paragraph summary at the top explaining why this release exists.
  • Verify the "Full Changelog" comparison link at the bottom is correct.

Edit the release body with:

gh release edit "${NEXT_VERSION}" --notes-file /tmp/release-notes.md \
  --repo Framework-R-D/action-handle-fix-commit

Step 7 — Verify the release

gh release view "${NEXT_VERSION}" --repo Framework-R-D/action-handle-fix-commit

Confirm:

  • draft: false
  • prerelease: false
  • Release body contains the "What's Changed" list and no <PR> placeholders.
  • Tag name matches ${NEXT_VERSION}.

Step 8 — Update README.md usage example

The README usage example should be pinned to the new version's commit SHA:

NEW_SHA=$(gh api repos/Framework-R-D/action-handle-fix-commit/git/ref/tags/${NEXT_VERSION} \
  --jq .object.sha)
# If the tag is annotated, dereference:
TYPE=$(gh api repos/Framework-R-D/action-handle-fix-commit/git/ref/tags/${NEXT_VERSION} \
  --jq .object.type)
if [ "$TYPE" = "tag" ]; then
  NEW_SHA=$(gh api repos/Framework-R-D/action-handle-fix-commit/git/tags/${NEW_SHA} \
    --jq .object.sha)
fi

# Update README.md
OLD_PATTERN="Framework-R-D/action-handle-fix-commit@[0-9a-f]\{40\} # v[0-9]*"
NEW_STRING="Framework-R-D/action-handle-fix-commit@${NEW_SHA} # ${NEXT_VERSION}"
sed -i "s|${OLD_PATTERN}|${NEW_STRING}|" README.md
git add README.md
git commit -m "docs: pin README usage example to ${NEXT_VERSION} SHA"
git push origin main

Step 9 — Update dependent action repositories (Level 1 and Level 2 only)

If this action is a dependency of other actions (check the dependency graph in AGENTS.md), file issues on those downstream action repos requesting a pin update, or open PRs directly. Dependabot will also pick this up on its weekly schedule.

Step 10 — Update phlex (or other consumers)

Open a PR on Framework-R-D/phlex updating the SHA pin for this action in all affected workflow files, if the update cannot wait for dependabot's weekly cycle.

Security notes

  • Never push a tag that points to an untrusted or unreviewed commit.
  • The tag commit must be on main (or a reviewed, merged commit).
  • Do not use --force when pushing tags; if a tag must be moved, delete it and re-create rather than force-pushing, and re-create the GitHub Release.
  • Pin all uses: references in action.yaml to commit SHAs. Version-tag pins (@v4) are supply-chain risks for composite actions.