📝 Document GitHub Flow branching model and agent task workflow
Adopt single-developer GitHub Flow: branches off main with a feature/fix/chore prefix, merged back via 'git merge --no-ff' (local PR). Releases are not triggered by pushes; only the maintainer runs 'npm run release', which tags and pushes; CI publishes to npm on the tag. Gitea is the lab; GitHub is reserved for later promotion. Replace the 'not yet settled' backlog note in AGENTS.md with concrete agent instructions: a task with subtasks gets a branch, a leaf task is worked on the current branch, and a fixed handover template (Implemented / Judgement calls / Known problems) frames the pre-merge review. Drop the stale 'MR' reference in 'Never do' (no MR workflow). Update the feedback-tier table and publishing workflow to gate CI on push to main, not PRs. Check off the branching-model backlog group and open a task for the release CI workflow (blocked on a missing Gitea runner).
This commit is contained in:
1 parent
75d605fabe
commit
06bc6bc43e
3 files changed
+39
-20
No files matched your search
+17
-14
@@ -46,8 +46,8 @@ The tools are organized into a feedback ladder. Each tier catches different thin
|
||||
| `npm run verify` | manual | Definition of done: `npm run check` + unit tests, one shot | ~6s |
|
||||
| `npm run fix` | manual | Auto-resolve fixable issues (lint, format) | ~3s |
|
||||
| `npm run maintain` | manual / CI (advisory) | `maintain:knip` + `maintain:outdated` (whole-project + network scans) | ~10s |
|
||||
| CI build (auto) | on push/PR | `npm run check` + `npm run test:ci` | ~30s+ |
|
||||
| CI maintain (auto, non-blocking) | on push/PR | `npm run maintain` — reports, never fails the build | ~10s |
|
||||
| CI build (auto) | on push to `main` | `npm run check` + `npm run test:ci` | ~30s+ |
|
||||
| CI maintain (auto, non-blocking) | on push to `main` | `npm run maintain` — reports, never fails the build | ~10s |
|
||||
| CI publish (auto) | on tag | `publish:publint` + `publish:attw`, then `npm publish` | ~10s |
|
||||
|
||||
### Why these splits?
|
||||
@@ -71,18 +71,21 @@ For this library the types _are_ the feature — narrowing, `exhaustive()` retur
|
||||
|
||||
This is why every test in the suite pairs an `expectTypeOf(...)` with an `assert.*` — keep them together. Type-first is also enforced structurally: `npm test` runs `check:tsc` before the test runner, so a wrong type can never be papered over by a passing assertion. Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix the types so both the type check and the runtime assertion pass, never suppress the ones you can't make pass.
|
||||
|
||||
## Branching model
|
||||
|
||||
**GitHub Flow (single-developer).** Every change — feature, fix, refactor — branches off `main` and is merged back via a local commit (no PR workflow on Gitea yet). Collaborative review via Gitea UI is not in place — Gitea is the lab; when something is tested and ready for production it will be promoted to GitHub.
|
||||
|
||||
- **Base branch:** `main`
|
||||
- **Branch naming:** `feature/<desc>` / `fix/<desc>` / `chore/<desc>`
|
||||
- **Merging:** `git checkout main && git merge --no-ff <branch>` (local PR — review the diff yourself before closing the branch).
|
||||
- CI runs `npm run check` + `npm run test:ci` on every push to `main` — this is the authoritative gate.
|
||||
- **Releases are NOT triggered by pushes.** Only the maintainer triggers a release (see [Publishing workflow](#publishing-workflow)).
|
||||
|
||||
## Publishing workflow
|
||||
|
||||
Publishing is CI-only by policy. Local `npm publish` is not supported.
|
||||
Publishing is CI-only by policy. Local `npm publish` is not supported. The maintainer triggers releases from `main`:
|
||||
|
||||
1. Develop and merge PRs to `main`.
|
||||
2. CI runs `npm run check` + `npm run test:ci` on every push and PR — this is the authoritative gate.
|
||||
3. After all intended changes are on `main`, bump the version locally:
|
||||
```sh
|
||||
npm version <patch|minor|major>
|
||||
```
|
||||
4. Push the tag to the forge (Gitea):
|
||||
```sh
|
||||
git push --follow-tags origin main
|
||||
```
|
||||
5. The `publish` CI job runs on the tag: `build` → `publish:publint` → `publish:attw` → `npm publish --access public`. The publish-tier checks must pass before the artifact is published.
|
||||
1. All intended changes are merged to `main` and passing CI.
|
||||
2. The maintainer runs `npm run release` — an interactive prompt suggests a version (based on the latest CHANGELOG entry); the maintainer confirms or edits it.
|
||||
3. `scripts/release.sh` creates a single release commit (changelog + package.json bump, amended into one commit), tags it, and pushes everything to Gitea.
|
||||
4. CI runs on the push: `npm run check` + `npm run test:ci` on the commit; then the `publish` job fires on the tag: `build` → `publish:publint` → `publish:attw` → `npm publish --access public`. The publish-tier checks must pass before the artifact is published.
|
||||
Reference in new issue
Block a user