Skip to content

chore: document feature worktree workflow #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Postlog merged 1 commit into from
Jun 28, 2026
Merged

chore: document feature worktree workflow #120

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ go.work.sum
# Tooling scratch (Playwright MCP traces/console logs)
.playwright-mcp/

# Feature worktrees live in-repo under .worktrees/<slug> (one branch per feature/fix)
.worktrees/

# OS / editor noise
.DS_Store
._*
Expand Down
19 changes: 19 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -525,6 +525,25 @@ scenario. Turnkey run: `make -C apitest test`.
- Required arrays (`groups`/`rules`/`providers`/`inbounds`/…) are decoded strictly by the server: `null`
(what a nil slice is JSON-encoded into) is rejected — send empty `[]`.

## Working on a change — worktree, branch, PR

Every feature/fix is developed in its **own git worktree on its own branch** — never
directly on `main` in the main checkout. This keeps `main` clean and switchable, isolates
parallel work, and makes branch → commit → push → PR the only path into `main`.

- **Create a worktree** off a clean `main`:
`git worktree add -b <type>/<slug> .worktrees/<slug>` — `<type>` ∈ `feat`/`fix`/`chore`
(e.g. `feat/subscription-link-catalog`). Worktrees live **in-repo** under `.worktrees/`,
which is gitignored, so the checkouts never show up in `git status`.
- **Do all development and commits in the worktree** (`cd .worktrees/<slug>`); the main
checkout stays untouched.
- **Run the full check before pushing** (`make all` — build+vet+lint+unit+integration+
apitest) and confirm it is green; a green push is not a substitute for the gate.
- **Push the branch and open a PR.** Do **not** push to or merge straight into `main` —
changes land via a reviewed, approved PR (squash-merge). Each PR carries its CHANGELOG
entry (and an ADR for non-trivial changes — see below).
- **After merge**, clean up: `git worktree remove .worktrees/<slug>` and delete the branch.

## Documenting changes — CHANGELOG + ADR

Every PR leaves a trace, so that «what and why we changed» does not get lost in the
Expand Down
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,13 @@ link to an ADR in [`docs/decisions/`](docs/decisions/). The rule and format are
in [`AGENTS.md`](AGENTS.md) (section "Documenting changes"). There are no versions/tags:
the service is not released, deploy is continuous.

## 2026-06-28 — Feature worktree workflow (#120)

Documented the per-feature workflow in `AGENTS.md`: every feature/fix is developed in its
own git worktree under `.worktrees/<slug>` on its own branch (branch → commit → push → PR;
never edit `main` directly). Added `.worktrees/` to `.gitignore` so those in-repo checkouts
never pollute `git status`.

## 2026-06-19 — Responsive admin UI: phones, tablets, ultrawide (#115)

Made the admin panel usable on every screen size — mini-phones (320px) through ultrawide.
Expand Down
Loading