Release workflow

Release Workflow

Step-by-step checklist for deploying an amendment release, from initial proposal through to the published bylaws on the website.

---

Prerequisites

• Push access to the repository
• Node.js installed, with npm install completed in the repo root
• Git configured for commits and tagging
• Membership in @CatholicOS/board (required for BYLAWS.md approval)

---

Phase 1 — Propose the amendment

1. Create an amendment branch from main:

   git checkout main && git pull
   git checkout -b amendment/YYYY-NN-short-title

   The branch name must match the pattern amendment/YYYY-NN-short-title (e.g. amendment/2026-02-quorum-threshold). CI will reject any other pattern when BYLAWS.md is modified.

2. Edit BYLAWS.md with the proposed changes.

   • Do not update the Version: or Last Amended: fields — the merge script sets these automatically from the tag.
   • Optionally update CHANGELOG.md.

3. Do not modify any other files in the amendment branch. CI enforces that only BYLAWS.md and CHANGELOG.md are changed.

4. Commit and push the branch:

   git add BYLAWS.md
   git commit -m "Amendment YYYY-NN: short description"
   git push -u origin amendment/YYYY-NN-short-title

---

Phase 2 — Open and review the Pull Request

5. Open a Pull Request against main. The PR template will load automatically — fill in every section:

   • Amendment ID and proposed version increment
   • Summary of changes (articles/sections affected)
   • Rationale
   • Approval authority (Board resolution, members' vote, etc.)

6. CI checks run automatically on the PR:

   • Markdown Lint — validates formatting of all .md files.
   • Governance Enforcement — verifies the amendment branch name.
   • Bylaws Approval Check — requires at least 3 approvals from @CatholicOS/board members before the PR can merge.

7. Obtain formal approval outside of GitHub (Board resolution, members' vote, etc.) as required by the bylaws. Record the resolution number or date in the PR's "Approval record" section.

8. Collect the required reviews on the PR (minimum 3 approvals).

---

Phase 3 — Merge, tag, and deploy

9. Merge and tag using the npm helper:

   npm run merge -- <PR_NUMBER> <TAG>

   For example:

   npm run merge -- 7 v1.1

   This command automates the entire merge-and-tag flow:

   • Checks out the PR branch and updates BYLAWS.md — sets Last Amended: to today and Version: to match the tag
   • Pushes the update commit to the PR branch
   • Waits for CI checks to pass
   • Merges the PR into main using a merge commit (no squash/rebase)
   • Updates local main and deletes the amendment branch
   • Creates an annotated tag and pushes it to origin

   If you want to merge without tagging (e.g. to tag later), omit the tag:

   npm run merge -- 7

10. CI validates the tag automatically:

    • Tag name matches vMAJOR.MINOR format
    • Tag name matches the Version: declared in BYLAWS.md
    • Last Amended: date matches the tagged commit's date

11. Deployment triggers automatically — once governance enforcement passes on the tag push, the Deploy Bylaws to WordPress workflow:

    • Converts BYLAWS.md to HTML via Pandoc
    • Publishes or updates the bylaws page on the WordPress site

---

Quick-reference checklist

[ ] Branch created: amendment/YYYY-NN-short-title
[ ] BYLAWS.md edited with version incremented
[ ] PR opened using the amendment template
[ ] CI checks passing (lint, branch name, approval count)
[ ] Formal approval obtained and recorded in PR
[ ] 3+ board approvals on the PR
[ ] npm run merge -- <PR> vX.Y executed
[ ] CI tag validation passing
[ ] WordPress deployment confirmed

---

Troubleshooting

CI fails with "Last Amended date does not match tagged commit date"

The tag was created without using npm run merge or npm run tag, so the date in BYLAWS.md is stale. Delete the tag, run npm run tag -- vX.Y on main, and push again:

git tag -d vX.Y
git push origin :refs/tags/vX.Y
npm run tag -- vX.Y
git push origin vX.Y

CI fails with "Tag does not match BYLAWS.md version"

The Version: field in BYLAWS.md was not incremented to match the tag. Go back and amend the version in a new commit before tagging.

npm run merge fails with "PR is not open"

The PR may have already been merged or closed. Check its state with gh pr view <PR_NUMBER>.

Bylaws Approval Check fails

The PR needs at least 3 approvals from @CatholicOS/board members. Request additional reviews before merging.