Skip to content

Commit 9d562da

Browse files
homebysixhomebysix
committed
Updated release docs and fixed version-skipping bug in workflow
1 parent 71ff7a7 commit 9d562da

3 files changed

Lines changed: 108 additions & 46 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 51 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,42 @@ jobs:
2929
echo "version=$(python ./setup.py --version)" >> $GITHUB_OUTPUT
3030
echo "Version detected: $(python ./setup.py --version)"
3131
32+
- name: Validate version alignment
33+
run: |
34+
VERSION="${{ steps.getversion.outputs.version }}"
35+
ERRORS=0
36+
37+
# Check CHANGELOG.md has the version section
38+
if ! grep -q "^## \[$VERSION\]" CHANGELOG.md; then
39+
echo "::error file=CHANGELOG.md::CHANGELOG.md is missing a section for version [$VERSION]. The workflow extracts release notes from the CHANGELOG, so this section must exist before releasing. Expected format: '## [$VERSION] - YYYY-MM-DD'"
40+
ERRORS=1
41+
fi
42+
43+
# Check README.md has the version
44+
if ! grep -q "rev: v$VERSION" README.md; then
45+
CURRENT_README_VERSION=$(grep -m 1 "rev: v" README.md | sed -n 's/.*rev: v\([0-9.]*\).*/\1/p')
46+
echo "::error file=README.md::README.md version (v$CURRENT_README_VERSION) does not match setup.py version ($VERSION). Update all 'rev: v' references in README.md to 'rev: v$VERSION' before releasing."
47+
ERRORS=1
48+
fi
49+
50+
# Check version link exists in CHANGELOG.md
51+
if ! grep -q "^\[$VERSION\]:" CHANGELOG.md; then
52+
echo "::error file=CHANGELOG.md::CHANGELOG.md is missing a version comparison link for [$VERSION]. Add '[$VERSION]: https://github.com/homebysix/pre-commit-macadmin/compare/vPREVIOUS...v$VERSION' at the bottom of CHANGELOG.md."
53+
ERRORS=1
54+
fi
55+
56+
if [ $ERRORS -gt 0 ]; then
57+
echo ""
58+
echo "❌ Version alignment check failed. Please ensure:"
59+
echo " 1. CHANGELOG.md has a '## [$VERSION]' section with release notes"
60+
echo " 2. README.md has 'rev: v$VERSION' in all examples"
61+
echo " 3. CHANGELOG.md has a '[$VERSION]:' comparison link at the bottom"
62+
echo ""
63+
exit 1
64+
fi
65+
66+
echo "✅ Version $VERSION is properly aligned across all files"
67+
3268
- name: Fetch tags
3369
run: git fetch --tags origin
3470

@@ -84,56 +120,32 @@ jobs:
84120
echo "next=$NEXT_VERSION" >> $GITHUB_OUTPUT
85121
echo "Next version will be: $NEXT_VERSION"
86122
87-
- name: Update setup.py version
123+
- name: Merge main to dev
88124
if: steps.tagcheck.outputs.should_release == 'true'
89125
run: |
90-
sed -i 's/version="${{ steps.getversion.outputs.version }}"/version="${{ steps.nextversion.outputs.next }}"/' setup.py
126+
git config user.name "github-actions[bot]"
127+
git config user.email "github-actions[bot]@users.noreply.github.com"
128+
git fetch origin dev
129+
git checkout dev
130+
git merge origin/main --no-edit
91131
92-
- name: Update README.md version
132+
- name: Update setup.py version on dev
93133
if: steps.tagcheck.outputs.should_release == 'true'
94134
run: |
95-
sed -i 's/rev: v${{ steps.getversion.outputs.version }}/rev: v${{ steps.nextversion.outputs.next }}/g' README.md
135+
sed -i 's/version="${{ steps.getversion.outputs.version }}"/version="${{ steps.nextversion.outputs.next }}"/' setup.py
96136
97-
- name: Update CHANGELOG.md
137+
- name: Update README.md version on dev
98138
if: steps.tagcheck.outputs.should_release == 'true'
99139
run: |
100-
CURRENT="${{ steps.getversion.outputs.version }}"
101-
NEXT="${{ steps.nextversion.outputs.next }}"
102-
TODAY=$(date +%Y-%m-%d)
103-
104-
# Create temp file with new changelog section
105-
cat > /tmp/changelog_update.txt << 'ENDOFCHANGELOG'
106-
## [Unreleased]
107-
108-
Nothing yet.
109-
110-
## [NEXT_VERSION] - TODAY_PLACEHOLDER
111-
ENDOFCHANGELOG
112-
113-
# Replace placeholders
114-
sed -i "s/NEXT_VERSION/$NEXT/g" /tmp/changelog_update.txt
115-
sed -i "s/TODAY_PLACEHOLDER/$TODAY/g" /tmp/changelog_update.txt
116-
117-
# Insert new section after the first "## [Unreleased]" line
118-
sed -i "/## \[Unreleased\]/r /tmp/changelog_update.txt" CHANGELOG.md
119-
# Remove the old "## [Unreleased]" and "Nothing yet." lines
120-
sed -i '1,/Nothing yet\./ { /## \[Unreleased\]/d; /Nothing yet\./d }' CHANGELOG.md
121-
122-
# Update version comparison links at bottom
123-
# Update [Unreleased] link
124-
sed -i "s|\[Unreleased\]:.*|[Unreleased]: https://github.com/homebysix/pre-commit-macadmin/compare/v$NEXT...HEAD|" CHANGELOG.md
125-
# Add new version link after [Unreleased]
126-
sed -i "/\[Unreleased\]:/a [$NEXT]: https://github.com/homebysix/pre-commit-macadmin/compare/v$CURRENT...v$NEXT" CHANGELOG.md
140+
sed -i 's/rev: v${{ steps.getversion.outputs.version }}/rev: v${{ steps.nextversion.outputs.next }}/g' README.md
127141
128-
- name: Commit version bump
142+
- name: Commit version bump on dev
129143
if: steps.tagcheck.outputs.should_release == 'true'
130144
run: |
131-
git config user.name "github-actions[bot]"
132-
git config user.email "github-actions[bot]@users.noreply.github.com"
133-
git add setup.py README.md CHANGELOG.md
134-
git commit -m "Bump to ${{ steps.nextversion.outputs.next }} [skip ci]"
145+
git add setup.py README.md
146+
git commit -m "Bump to ${{ steps.nextversion.outputs.next }}"
135147
136-
- name: Push changes
148+
- name: Push dev branch
137149
if: steps.tagcheck.outputs.should_release == 'true'
138150
run: |
139-
git push origin main
151+
git push origin dev

‎CHANGELOG.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,15 @@ All notable changes to this project will be documented in this file. This projec
1212

1313
## [Unreleased]
1414

15+
Nothing yet.
16+
17+
## [1.24.1] - 2026-04-12
18+
1519
### Changed
1620

1721
- Skipped AutoPkg recipe type convention checks when type is unknown. (#55)
22+
- Updated release documentation to reflect new automated workflow.
23+
- Built error handling into release automation workflow.
1824

1925
## [1.24.0] - 2026-04-12
2026

@@ -470,7 +476,8 @@ All notable changes to this project will be documented in this file. This projec
470476

471477
- Initial release
472478

473-
[Unreleased]: https://github.com/homebysix/pre-commit-macadmin/compare/v1.24.0...HEAD
479+
[Unreleased]: https://github.com/homebysix/pre-commit-macadmin/compare/v1.24.1...HEAD
480+
[1.24.1]: https://github.com/homebysix/pre-commit-macadmin/compare/v1.24.0...v1.24.1
474481
[1.24.0]: https://github.com/homebysix/pre-commit-macadmin/compare/v1.23.0...v1.24.0
475482
[1.23.0]: https://github.com/homebysix/pre-commit-macadmin/compare/v1.22.0...v1.23.0
476483
[1.22.0]: https://github.com/homebysix/pre-commit-macadmin/compare/v1.21.0...v1.22.0

‎RELEASING.md‎

Lines changed: 49 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,58 @@
11
# Releasing new versions of pre-commit-macadmin
22

3-
1. Update the versions in __README.md__ and __setup.py__.
3+
Releases are largely automated via GitHub Actions. The workflow triggers when `setup.py` is pushed to `main`, creating a GitHub release and automatically preparing the `dev` branch for the next release.
44

5-
1. Check unit tests:
5+
## Release Process
6+
7+
1. On the `dev` branch, check unit tests:
68

79
.venv/bin/python -m coverage run -m unittest discover -vs tests
810

9-
1. Update the change log.
11+
1. Prepare CHANGELOG.md for release by moving `[Unreleased]` changes to a new version section:
12+
13+
## [Unreleased]
14+
15+
Nothing yet.
16+
17+
## [X.Y.Z] - YYYY-MM-DD
18+
19+
### Added/Changed/Fixed/Removed (separate sections as applicable)
20+
- New features, changes, fixes, or removals
21+
22+
The release workflow will extract this section for the GitHub release notes.
23+
24+
1. Add the version comparison link at the bottom of CHANGELOG.md:
25+
26+
[X.Y.Z]: https://github.com/homebysix/pre-commit-macadmin/compare/vPREVIOUS...vX.Y.Z
27+
28+
1. Update the version in `setup.py` to match the CHANGELOG version (e.g., `2.3.6`).
29+
30+
1. Update the version in `README.md` examples to match (e.g., `rev: v2.3.6`).
31+
32+
1. Commit these changes to `dev` and push.
33+
34+
1. Merge `dev` branch to `main`.
35+
36+
1. The release workflow will automatically:
37+
- Detect the version from `setup.py` (e.g., `2.3.6`)
38+
- Create a GitHub release with tag `v2.3.6`
39+
- Extract release notes from CHANGELOG.md
40+
- Merge `main` back to `dev`
41+
- Bump `dev` versions to the next patch version (e.g., `2.3.7`) in `setup.py` and `README.md`
42+
- Commit and push the updated version to `dev`
43+
44+
Note: CHANGELOG.md is NOT automatically updated on `dev`. Add entries to the `[Unreleased]` section as you make changes.
45+
46+
1. Pull the updated `dev` branch to continue development at the new version.
47+
48+
1. As you make changes, add entries to the `[Unreleased]` section of CHANGELOG.md. When ready for the next release, simply promote those changes to a new version section (repeat from step 2) - no need to manually bump versions unless you want to change to a minor or major version.
49+
50+
1. After each release, verify on GitHub and run `pre-commit autoupdate` on a test repo to confirm it updates correctly.
51+
52+
## Version Numbering
1053

11-
1. Merge development branch to main.
54+
The workflow automatically bumps the **patch** version (X.Y.Z → X.Y.Z+1). If you need to bump the **minor** or **major** version, manually update the version numbers in `setup.py`, `README.md`, and CHANGELOG.md before merging to `main`.
1255

13-
1. Create a GitHub release with version tag, prefixed with `v`. (For example: `v2.3.4`)
56+
## Pre-releases
1457

15-
1. Run `pre-commit autoupdate` on a test repo and confirm it updates to the new version.
58+
If a pre-release is desired for testing purposes, it must be done manually.

0 commit comments

Comments
 (0)