didericis
1df78ee77f
Add docs/decisions/ with a convention README and back-fill two decisions that previously had no in-repo home: merging PRs with rebase (ADR 0001) and the agent-identity claimed-not-vouched trust posture from PRD 0027 (ADR 0002). Point docs/INDEX.md at it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2.1 KiB
2.1 KiB
ADR 0001: Merge PRs with rebase, not merge commits
- Status: Accepted
- Date: 2026-05-28
- Deciders: didericis
Context
PRs need a merge strategy. Gitea offers merge-commit, squash, rebase,
and rebase-merge. The project uses Conventional
Commits enforced by a
commit-msg hook, and PRDs typically land as a multi-commit PR where
each commit is meaningful on its own (e.g. PR #95: a docs(prd) commit,
a feat(manifest) implementation commit, and a docs(manifest)
commit). The history should stay readable and the individual
conventional commits should survive onto main.
Decision
Merge PRs with rebase (Gitea's rebase style; Do: "rebase" via
the API). The branch's commits are replayed onto main with no merge
commit, producing a linear history that preserves each commit verbatim.
Consequences
- Linear history, no merge bubbles;
git log --onelinereads as a straight sequence of conventional commits. - Each commit is preserved (unlike squash, which would collapse the PRD/impl/docs commits into one and lose the staged structure).
- Commit SHAs are rewritten at merge. The replayed commits on
mainget new SHAs, and the source branch is deleted, so a link to a file by branch name (/src/branch/<feature>/…) dies at merge. This is why links to not-yet-merged files are pinned to a commit SHA (/src/commit/<sha>/…), which stays reachable via the retainedrefs/pull/<n>/headref. Seedocs/research/issue-tracking-vs-in-repo-decision-history.md. - Trade-off accepted: without a merge commit, the "these commits landed together as PR #N" grouping is not recorded in git itself — it lives in forge state (the PR). That is a mild concession against the keep-history-in-the-repo posture; the conventional-commit scopes and PRD references in the messages keep changes traceable without it.
Links
docs/research/issue-tracking-vs-in-repo-decision-history.md— the commit-pinning consequence above.- Observed practice: PRs #92, #93 merged with rebase; #95 to follow.