Skip to content

docs(contributing): state the branch-refresh discipline — rebase in place, never hand-carry main #693

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
c03rad0r merged 2 commits into from
Oct 6, 2026
Merged

docs(contributing): state the branch-refresh discipline — rebase in place, never hand-carry main #693

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c54e798
docs(contributing): state the branch-refresh discipline — rebase in p…
Oct 6, 2026
7edce81
Merge branch 'main' into docs/rebase-in-place-guard
c03rad0r Oct 6, 2026
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
13 changes: 13 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,19 @@ and [Semantic Versioning](https://semver.org/).
[`docs/architecture/walletport-contract.md`](docs/architecture/walletport-contract.md#5-candidate-mapping-first-pass).
([#631](https://github.com/OpenTollGate/tollgate-module-basic-go/pull/631))

### Changed / Internal

- **CONTRIBUTING now states the branch-refresh discipline: rebase in
place, never hand-carry `main`.** Merging `main` forward into a PR
branch (evil merges, a `go.sum` equal to neither parent, replayed
thousand-line diffs) and opening fresh "rebase of #N" PRs (zombie
originals nobody closes) are both named as anti-patterns, with the
in-place recipe: rebase onto current `main`, run the battery,
`--force-with-lease` the original PR branch, close what you supersede
in the same action, and keep carried CHANGELOG entries under
`[Unreleased]` with their PR link.
([#693](https://github.com/OpenTollGate/tollgate-module-basic-go/pull/693))

## [v0.6.0-rc1] - 2026-10-05
### Added

Expand Down
23 changes: 23 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,29 @@ running it yourself saves a review round trip.
- **Commit message references the bug**: the symptom, the root cause
in one sentence, and the fix shape.

### Keeping a PR current: rebase in place, never hand-carry `main`

Long-lived branches go stale, and the two common ways of refreshing them
both damage the queue. Do not merge `main` forward into a PR branch — in
this multi-module tree it breeds evil merges (a `go.sum` that equals
neither parent) and, done as a squash, a single-parent "merge" commit that
replays thousands of `main` lines into the PR diff. Do not open a fresh
"rebase of #N" PR either — the original stays open as a zombie and nobody
can tell which one is live. Instead, refresh the branch the PR already
has:

```bash
git fetch origin
git rebase origin/main # or: git merge --squash <pr-head> onto a fresh main
make go-battery # plus the offline suites your diff touches
git push --force-with-lease origin <pr-branch>
```

If a rebase-PR was already opened, close the superseded original in the
same action. CHANGELOG entries carried by the rebased commits belong under
`[Unreleased]` with their PR link — an entry landing inside an
already-dated release section is the standard stale-rebase artifact.

### Merge mechanics

PRs are merged via **squash-merge**. One logical change per PR becomes
Expand Down