From 970d5f652018458d6856a291f621736f71098bef Mon Sep 17 00:00:00 2001 From: dtzp555 Date: Sat, 7 Mar 2026 20:15:06 +1000 Subject: [PATCH] docs: improve README and add usage notes --- README.md | 92 ++++++++++++++++++++++++++++++++++++++++--------------- USAGE.md | 30 ++++++++++++++++++ 2 files changed, 98 insertions(+), 24 deletions(-) create mode 100644 USAGE.md diff --git a/README.md b/README.md index 4e9addb..c4cf733 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,41 @@ # 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 +A lightweight skill for GitHub repos that block direct pushes to `main`, require pull requests, and expect release work to happen **after merge**. + +This repo exists to encode one practical workflow: + +> **PR first, release after merge.** ## Why this exists -We kept running into the same avoidable problems: +A lot of GitHub workflow pain is repetitive, not interesting: - 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 +- assuming `approvals = 0` means direct push is allowed +- discussing release updates before the relevant changes are merged +- forgetting to check whether `package.json`, git tags, and GitHub releases are aligned -This skill turns that repeated pain into a default workflow. +This skill turns those repeated mistakes into a default operating habit. -## What it helps with +## What this skill 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 +- switch from local commits to branch + PR flow quickly +- decide whether release work must wait until after merge +- keep version / tag / release state from drifting apart +- stop repeating the same protected-branch mistakes + +## When to use it + +Use this skill when you are working in a GitHub repo and any of these are true: +- direct push to `main` may be blocked +- the repo uses branch protection / PR-only rules +- you need to open a PR after local work +- you need to decide whether a release should happen now or wait for merge +- you keep re-learning the same GitHub publishing flow from scratch ## Default policy -If repo rules are unclear, prefer: +If repo rules are unknown, prefer this order: 1. local commit 2. branch 3. push branch @@ -33,16 +43,50 @@ If repo rules are unclear, prefer: 5. merge 6. release -In other words: **PR first, release after merge**. +In short: **PR first, release after merge**. -## Suggested use cases +## Example situations -- docs updates that still must go through PR -- feature work in protected repos -- patch releases after merge -- repos with branch protection / PR-only rules +### Example 1: docs change in a protected repo +You update README locally, commit, try to push, and GitHub rejects direct push to `main`. -## Notes +Correct move: +- keep the local commit +- create a branch +- push the branch +- open a PR -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. +### Example 2: user says “update the release” +Before touching the release: +- check whether the intended changes are already merged +- inspect current version, tags, and releases +- if changes are still only in an open PR, wait or explicitly create a prerelease/draft + +### Example 3: approvals are set to 0 +That still does **not** prove direct push is allowed. +Branch protection may still require PRs. + +## What this skill does not try to be + +This is **not** a general GitHub encyclopedia. +It is intentionally narrow: +- protected branch / PR-first repos +- release-after-merge workflow +- practical decision rules + +## Repo contents + +- `SKILL.md` — the actual skill instructions for agent use +- `README.md` — human-readable overview and examples + +## Suggested next improvements + +Future iterations can add: +- PR body examples +- release notes examples +- repo-rule detection checklist +- examples for patch vs minor release decisions + +## License + +MIT diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 0000000..00d4dc9 --- /dev/null +++ b/USAGE.md @@ -0,0 +1,30 @@ +# Usage notes + +This repo is meant to stay lightweight. + +## Basic usage idea + +When working in a GitHub repo: +1. inspect branch / status / tags / releases if needed +2. assume PR-first if repo rules are unclear +3. avoid release work until the relevant changes are merged + +## Mental checklist + +Before pushing: +- Am I on `main`? +- Does this repo allow direct push to `main`? +- If I do not know, why am I not using a branch + PR? + +Before changing a release: +- Are the intended changes already merged? +- Does `package.json` version match the intended release? +- Are git tags and GitHub releases in sync? + +## Core rule + +If uncertain, do the safer thing: +- branch +- PR +- merge +- release