56 lines
2.9 KiB
Markdown
56 lines
2.9 KiB
Markdown
---
|
||
name: serverappconfigs-docs-only-landing
|
||
description: "Land a docs-only (vault/log) commit on serverAppConfigs main without a PR: tests green, then fast-forward main via git push origin HEAD:main — including recovery when the omp worktree base is stale or pre-compaction edits vanished."
|
||
---
|
||
|
||
# serverAppConfigs docs-only landing
|
||
|
||
Land vault/log edits on `main` directly (no PR) when the change touches only
|
||
`serverAppConfigs-docs/**` (or `AGENTS.md`): the deployer treats docs-only
|
||
changes as a no-op, and origin is the self-hosted Gitea — pushing there is
|
||
allowed.
|
||
|
||
## Procedure
|
||
|
||
1. **Ground-truth the worktree BEFORE editing** (omp worktrees go stale
|
||
between sessions/compactions):
|
||
- `git fetch origin && git log --oneline 3e140cd..origin/main`-style check:
|
||
`git log --oneline HEAD..origin/main` — if non-empty, main advanced
|
||
(sibling sessions land zealot/dankclaw work constantly).
|
||
- NEVER trust the session summary that "file X was already edited": the
|
||
worktree may sit at an older commit and transcript-era edits may not
|
||
exist on disk. Verify with `grep -n "<new-phrase>" <file>`; redo edits
|
||
against a fresh read if absent.
|
||
- Line numbers in AGENTS.md shift between main versions — re-locate stale
|
||
claims by `grep -n "on disk\|stays on disk\|rollback target" AGENTS.md`,
|
||
never by remembered line numbers.
|
||
2. Edit (read target regions fresh; long table rows in AGENTS.md must be
|
||
re-emitted whole via `PUT n.=n:` — get the full row first with
|
||
`read path:N:raw`).
|
||
3. `./tests/run.sh` — full bats suite must pass (~60–75 s; run async, do
|
||
other work). Docs seams of interest: `docs_completeness` (index links
|
||
every page, no unresolved `[[wikilinks]]`).
|
||
4. Commit on the worktree branch, then rebase onto `origin/main` if it
|
||
advanced. Typical conflict: `log.md` tail — both sides appended entries;
|
||
resolution = keep both blocks, `CUT` the three marker lines, re-add the
|
||
blank line before the second heading.
|
||
5. Re-run the docs seam (or full suite if non-prose changed) against the
|
||
exact pushed tree.
|
||
6. **Push:** `git push origin HEAD:main` — plain push IS the fast-forward
|
||
PR-less merge. NEVER `--force`/`--no-verify`. If Gitea rejects, main moved
|
||
again: rebase (step 4) and push again.
|
||
7. Docs-only = no `deploy.sh` run needed; hosts pick the pages up on their
|
||
next pull.
|
||
|
||
## Gotchas
|
||
|
||
- `git status` not listing a file you "just edited" + `rev-parse HEAD`
|
||
mismatch vs `git worktree list` → the harness recreated/reset the worktree;
|
||
the edits are gone. Redo, don't hunt.
|
||
- `log.md` entries: heading `## YYYY-MM-DD — topic`, blank line between
|
||
entries; docs seam tolerates either entry order within a day.
|
||
- Prose-only amend after a green suite: rerun at least
|
||
`bats tests/docs_completeness.bats` before push.
|
||
- Do not reset the shared `main` checkout in `~/Projects/serverAppConfig`;
|
||
it falls behind origin and the user syncs it.
|