From b87f8649088536ed6d06b8e7946ef15e7b676d03 Mon Sep 17 00:00:00 2001 From: dtzp555 Date: Sat, 7 Mar 2026 20:10:16 +1000 Subject: [PATCH] init: add GitHub PR and release workflow skill --- README.md | 48 +++++++++++++++++++++++++++ SKILL.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 README.md create mode 100644 SKILL.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4e9addb --- /dev/null +++ b/README.md @@ -0,0 +1,48 @@ +# gh-pr-release-flow + +A lightweight GitHub workflow skill for repos that: +- reject direct pushes to `main` +- require pull requests even when approvals are set to 0 +- need releases to happen **after merge**, not while work is still only in an open PR + +## Why this exists + +We kept running into the same avoidable problems: +- pushing to `main` and getting rejected by repo rules +- assuming `approvals = 0` meant direct push was allowed +- discussing release updates before the relevant changes were merged +- re-discovering the same GitHub flow every time + +This skill turns that repeated pain into a default workflow. + +## What it helps with + +- detect when a repo is effectively PR-only +- switch quickly from local commits to branch + PR flow +- decide whether release work should wait until after merge +- keep `package.json` version, git tag, and GitHub release from drifting apart +- avoid repeating the same repo-rule mistakes + +## Default policy + +If repo rules are unclear, prefer: +1. local commit +2. branch +3. push branch +4. PR +5. merge +6. release + +In other words: **PR first, release after merge**. + +## Suggested use cases + +- docs updates that still must go through PR +- feature work in protected repos +- patch releases after merge +- repos with branch protection / PR-only rules + +## Notes + +This is intentionally a narrow workflow skill, not a general GitHub encyclopedia. +It exists to encode one practical habit: stop bouncing off protected `main`, and stop releasing changes that have not landed yet. diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..f9a5a60 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,99 @@ +--- +name: gh-pr-release-flow +description: Handle GitHub repos that may block direct pushes to main and require pull-request-first delivery plus post-merge release work. Use when changing a GitHub repo and you need to: (1) detect whether direct pushes are blocked, (2) switch to branch + PR flow, (3) decide whether release work must wait until after merge, (4) create PRs, tags, and releases in the correct order, or (5) avoid repeating the 'push rejected, PR required' mistake. +--- + +# GitHub PR + release flow + +Default assumption: if repo rules are unknown, prefer **branch + PR** over direct push to `main`. + +## Core workflow + +1. Check current state before publishing changes: + - local branch + - unpushed commits + - latest release/tag/version if release is involved +2. Try to understand repo constraints early: + - if prior attempts showed `main` is PR-only, do not try direct push again + - if unsure, assume PR-only +3. For normal code/docs changes: + - commit locally + - create a branch + - push branch + - open PR +4. For release work: + - do **not** publish a release for changes that are still only in an open PR + - merge first, then bump version/tag/release from the merged state unless the repo has an explicit prerelease workflow + +## Common traps + +- `approvals = 0` does **not** mean direct pushes to `main` are allowed. +- Branch protection may still require PRs even when review count is zero. +- Package version, git tag, and GitHub release can drift; inspect all three before changing release state. +- "Latest release" may describe old `main` if newer work is only in a PR branch. + +## Publishing decision rules + +### If push to main is rejected +Treat that as a stable repo rule unless proven otherwise. + +Do this: +1. keep local commit(s) +2. create a descriptive branch +3. push branch +4. create PR +5. continue discussion/review there + +### If user asks to "update the release" +First determine whether the intended changes are already merged. + +- If **not merged**: explain that release should wait until merge, unless user explicitly wants a draft/prerelease. +- If **merged**: inspect `package.json` version, tags, and GitHub releases; then decide patch/minor bump. + +### If change is docs-only or packaging-only +Still follow repo rules. Do not assume docs can bypass PR requirements. + +## Recommended command pattern + +### Inspect +- `git branch --show-current` +- `git status --short` +- `git tag --sort=-creatordate | head` +- `gh release list --limit 10` +- `gh pr view ` / `gh pr list` + +### PR-first publish +- `git checkout -b ` +- `git push -u origin ` +- `gh pr create ...` + +### Post-merge release +1. switch to updated `main` +2. verify merged commits are present +3. bump version if needed +4. create tag +5. create GitHub release with concise notes + +## PR body template + +Use a compact structure: +- Summary +- Why +- Notes / follow-ups + +## Release note template + +Use a compact structure: +- Highlights +- Why this matters +- Upgrade / notes (only if needed) + +## When to be explicit with the user + +Always say so when: +- a repo rule blocks direct push +- release should wait for merge +- version/tag/release are out of sync +- you are switching from direct-push assumption to PR flow + +Keep the explanation short and operational, not theoretical.