diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d2d4cc432..85d68fbd1 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,9 +1,19 @@ ### Description Please include a summary of the change and which issue is fixed. Also include relevant motivation and context. +### Slice + +- Issue: # +- Scope / owning surface: +- Dependencies or overlapping PRs: None +
Checklist +- [ ] This branch started from current `staging` and does not include another unmerged PR unless it is named above. +- [ ] This is one independently reviewable slice; unrelated cleanup or refactors are in separate PRs. +- [ ] I checked open PRs for overlapping files, contracts, schemas, or deployment configuration and made any dependency explicit above. +- [ ] This PR targets `staging`; after it closes, this branch will not be reused for another change. - [ ] My code follows the style guidelines of this project - [ ] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas @@ -12,4 +22,4 @@ Please include a summary of the change and which issue is fixed. Also include re - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes -
\ No newline at end of file + diff --git a/AGENTS.md b/AGENTS.md index 56b610ae9..0bec822a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -153,7 +153,15 @@ For picker controls, use the component that matches the interaction: - For broad migrations, follow the repo’s existing pattern: one commit per meaningful area, e.g. `feat(dashboard): migrate home, events, insights, and links pages to shared UI components`. - Before committing, check `git diff --stat` and `git status --short`; if the diff mixes unrelated intents, split it. - Only make a single snapshot commit for the whole worktree when the user explicitly asks to include everything as-is. -- **PRs**: Open against `staging` branch (not `main`). + +## Branch and PR Lifecycle + +- **One task, one branch, one PR**: Keep a branch to one independently reviewable and reversible slice. If work can land separately, split it before it becomes a mixed PR. +- **Start fresh**: Check for an existing PR that owns the same surface, public contract, schema, or deployment configuration, then create the branch from an up-to-date `origin/staging`. Do not use an unmerged feature branch as a base unless the dependency is explicit, approved, and named as `Depends on #…` in both PRs. +- **Make ownership visible**: Push and open a draft PR against `staging` once the slice has a first commit. State its scope, dependencies, and known overlaps. +- **Keep integration linear**: Rebase a slice onto current `origin/staging` before it is ready for review; do not merge `staging` into the slice merely to refresh it. Request fresh review when a rebase changes reviewed code. +- **Isolate parallel work**: Use one worktree per active branch. Never let two agents or contributors mutate the same branch or reuse a task branch for a different concern. +- **Retire completed work**: Merged PR source branches are automatically deleted. Delete closed PR branches manually, remove clean finished worktrees, and create a new branch from current `staging` for any follow-up—never revive or repurpose an old PR branch. ## CI and Review Lessons diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af6121a5d..8a4d0d05e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -100,42 +100,72 @@ You can also `cd` into any package and run its scripts directly. ### Development Workflow -1. Create a new branch: +#### Branch and PR lifecycle + +Keep each branch short-lived: one branch, one independently reviewable and +revertible slice, one pull request. Do not use a branch as a general work +queue. + +1. Before starting, check open pull requests for the same surface, public + contract, schema, or deployment configuration. Update `staging`, then create + a fresh branch from it: ```bash -git checkout -b feature/your-feature +git switch staging +git pull --ff-only origin staging +git switch -c codex/short-slice ``` -2. Make your changes + Do not branch from another feature branch. An exception needs an explicit + `Depends on #…` in both PRs and agreement from its owner; land the + prerequisite first. + +2. Keep the branch to its stated slice. If a change can be reviewed or reverted + independently, open a separate branch and PR; leave unrelated cleanup and + refactors out of the current one. + +3. Push early and open a draft PR against `staging`. State the problem being + solved and any dependency or known overlap. This makes ownership visible + before parallel work drifts into the same files. + +4. Before requesting review, rebase onto the current `origin/staging` and + resolve the conflicts in the slice. Do not merge `staging` into a feature + branch just to refresh it. If the rebase changes reviewed code, request a + fresh review. -3. Run tests: +5. Run the relevant checks: ```bash bun run test ``` -4. Create a changeset: +6. Create a changeset when the change affects a published package: ```bash bun run changeset ``` -5. Commit your changes: +7. Commit your changes: ```bash git add . git commit -m "feat: your feature" ``` -6. Push your changes: +8. Push your changes: ```bash -git push origin feature/your-feature +git push -u origin codex/short-slice ``` -Note: Open a pull request to the STAGING branch +9. When the PR is merged or closed, retire the branch. GitHub automatically + deletes merged source branches; delete a closed branch manually. Never + repurpose or reopen an old branch for a new slice—start again from current + `staging`. -7. Create a Pull Request +For parallel work, use one worktree per branch and never have two people or +agents mutate the same branch. Remove a worktree only after its work is merged, +closed, or safely moved to a new branch. ## Code Style