Contributing: a branch per issue is asked for, but nothing says how to work on a second one beside the first #1146

New issue

Closed

opened 2026-10-31 03:04:20 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-10-31 03:04:20 +00:00

Owner

What exists today

CONTRIBUTING.md lines 54-80 (How a change reaches main) asks for a branch per issue and a pull request per branch, merged when CI is green. Nothing in CONTRIBUTING.md, scripts/ or the workflows mentions git worktree. With one checkout, a contributor waiting on CI for one branch (the browser job alone is around half an hour) has to stash and switch to start the next issue, which also invalidates the compiled .mo files and the static build for the branch left behind.

A worktree works but has traps nothing writes down:

It has no .venv (gitignored, line 4), no .env (line 17) and no compiled catalogues (*.mo, line 30): uv sync (fast from uv's shared cache) and scripts/messages.py compile (about 27 s, see W3) are needed before the first test.
The datasets under src/postulo/jobs/data are downloaded in place and gitignored (ESCO 11 MB, GeoNames 62 MB plus the derived 30 MB geonames-cities1000.sqlite): a worktree has none. The suite runs without them, as CI does, but the running app then has no place lookup unless POSTULO_GEOLOCATIONS_DIR (src/postulo/jobs/places.py:44-45) points at the main checkout's copy or manage.py fetch_geonames downloads them again.
The stash stack is shared between worktrees, and a running test suite in one beside the browser suite in the other starves the machine (the user's own notes record both).

Honest weight: for an occasional contributor working one issue at a time, branch switching is enough and the rule does not need worktrees. The win is for whoever runs several issues at once, which is how the maintainer works.

No duplicate: searches for "worktree", "git worktree" and "parallel branches" find only #940, which set the branch-per-issue rule without a recipe.

What would change

A short subsection under How a change reaches main, "Two issues at once", with the commands: git worktree add ../postulo-<N> -b <N>-<slug> origin/main, uv sync, copy .env, POSTULO_GEOLOCATIONS_DIR=<main checkout>/src/postulo/jobs/data in the worktree's .env, uv run python scripts/messages.py compile, and git worktree remove once merged; plus the two warnings (shared stash, one heavy suite at a time). Optionally a small scripts/worktree.py <issue> <slug> doing the same steps; the house rule (a library before own code) has nothing to offer here beyond git itself.

What it saves or protects

small: a documented worktree recipe that shares the 70 MB of downloaded datasets and the uv cache instead of re-downloading them, and avoids the known pitfalls; a convenience, not a saving on every run

Accessibility

none

Decided by the maintainer (2026-10-31)

CONTRIBUTING section only, no script

Decisions

Documentation only, or a script too? Recommended: documentation only; a script is one more thing to keep in step with the setup, for a step done a few times a week.

Found by the efficiency and reliability audit of 2026-10-30 (finding W4; index postulo/postulo#1108). Checked against main at daee30b15 (2026-10-30).

## What exists today `CONTRIBUTING.md` lines 54-80 (*How a change reaches main*) asks for a branch per issue and a pull request per branch, merged when CI is green. Nothing in `CONTRIBUTING.md`, `scripts/` or the workflows mentions `git worktree`. With one checkout, a contributor waiting on CI for one branch (the browser job alone is around half an hour) has to stash and switch to start the next issue, which also invalidates the compiled `.mo` files and the static build for the branch left behind. A worktree works but has traps nothing writes down: - It has no `.venv` (gitignored, line 4), no `.env` (line 17) and no compiled catalogues (`*.mo`, line 30): `uv sync` (fast from uv's shared cache) and `scripts/messages.py compile` (about 27 s, see W3) are needed before the first test. - The datasets under `src/postulo/jobs/data` are downloaded in place and gitignored (ESCO 11 MB, GeoNames 62 MB plus the derived 30 MB `geonames-cities1000.sqlite`): a worktree has none. The suite runs without them, as CI does, but the running app then has no place lookup unless `POSTULO_GEOLOCATIONS_DIR` (`src/postulo/jobs/places.py:44-45`) points at the main checkout's copy or `manage.py fetch_geonames` downloads them again. - The stash stack is shared between worktrees, and a running test suite in one beside the browser suite in the other starves the machine (the user's own notes record both). Honest weight: for an occasional contributor working one issue at a time, branch switching is enough and the rule does not need worktrees. The win is for whoever runs several issues at once, which is how the maintainer works. No duplicate: searches for "worktree", "git worktree" and "parallel branches" find only #940, which set the branch-per-issue rule without a recipe. ## What would change A short subsection under *How a change reaches main*, "Two issues at once", with the commands: `git worktree add ../postulo-<N> -b <N>-<slug> origin/main`, `uv sync`, copy `.env`, `POSTULO_GEOLOCATIONS_DIR=<main checkout>/src/postulo/jobs/data` in the worktree's `.env`, `uv run python scripts/messages.py compile`, and `git worktree remove` once merged; plus the two warnings (shared stash, one heavy suite at a time). Optionally a small `scripts/worktree.py <issue> <slug>` doing the same steps; the house rule (a library before own code) has nothing to offer here beyond git itself. ## What it saves or protects small: a documented worktree recipe that shares the 70 MB of downloaded datasets and the uv cache instead of re-downloading them, and avoids the known pitfalls; a convenience, not a saving on every run ## Accessibility none ## Decided by the maintainer (2026-10-31) CONTRIBUTING section only, no script ## Decisions - **Documentation only, or a script too?** Recommended: documentation only; a script is one more thing to keep in step with the setup, for a step done a few times a week. --- Found by the efficiency and reliability audit of 2026-10-30 (finding W4; index postulo/postulo#1108). Checked against `main` at `daee30b15` (2026-10-30).

tiagoagueda added this to the 0.6.0 milestone

2026-10-31 03:04:20 +00:00

tiagoagueda added the

performance

enhancement

documentation

labels

2026-10-31 03:04:20 +00:00

tiagoagueda referenced this issue

2026-10-31 03:04:41 +00:00

Efficiency and reliability audit of 2026-10-30: index #1108

tiagoagueda referenced this issue from a pull request that will close it,