docs: document push-daemon-as-durability + fix stale PVC/working-tree language in runbook
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 88/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Quiet
- Tech stack
- git
- Domain
- documentation
Research direction
Start with the "The data clone is bare" section in specs/behaviors/storage.md and the relevant "Fetch from the pod's data clone" section in docs/operations/runbook.md. Document the emptyDir durability tradeoff, push-daemon verification, and bare-clone reality, then check that the stale PVC and working-tree wording is gone and both files agree.
Written by the indexing model from the issue text.
Description
Background
PR #86 switched the data-repo volume from PVC to emptyDir and made the clone bare. Two doc gaps remain:
1. Durability tradeoff is undocumented
With emptyDir, the bare clone is wiped on every pod boot. If the pod crashes (OOM, node failure, hard kill) before the push daemon has shipped locally-committed gitsheets writes to origin, those commits are lost — the volume goes away before any container code (reconcile, escape-hatch) can run.
Today's reconcile escape-hatches local-ahead commits to conflicts/<UTC> only when the container restarts cleanly enough to invoke reconcileDataRepo. On a hard crash, that path never runs.
Mitigating factor: the push daemon runs continuously with retry/backoff, so the window of unpushed local state is small. But this is now a meaningful change in the durability story vs. the previous PVC-backed setup, and it should be documented as an explicit operating constraint.
Where to add:
specs/behaviors/storage.md— under "The data clone is bare", a short subsection: "Durability: writes are durable onceorigin/<branch>has them. The push daemon is the only line of defense for in-flight commits; on hard pod crash before the next push, local commits are lost."docs/operations/runbook.md— in the "API won't boot" or a new "Durability" section, the same note plus a pointer to the push daemon's lag/log for verification.
2. Stale wording in runbook's "Fetch from the pod's data clone" section
docs/operations/runbook.md — the section that documents the git-pod-uploadpack.sh operator helper still says:
The pod's working tree lives on a PVC at
/app/datainside the container...
After PR #86 that's incorrect on both counts — it's now a bare gitdir on an emptyDir. Update to reflect bare-clone reality. Reference specs/behaviors/storage.md → "The data clone is bare".
Scope
Single PR. Maybe ~30 lines of diff total.
Filed as follow-up from PR #86.
- Dominant language
- TypeScript
- Stars
- 1
- Forks
- 1
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from CodeForPhilly/codeforphilly-ng
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
-
MarkdownEditor toolbar: use Radix Toolbar from radix-ui instead of the hand-rolled roving tabindex Openenhancement
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
-
Difficulty 1/5 Under an hour Newbie friendliness 82/100
All issues in CodeForPhilly/codeforphilly-ng
Similar issues
-
calcite-components needs triage refactor
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Esri/calcite-design-system#15203 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 91/100
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficulty 1/5 Under an hour Newbie friendliness 95/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Automattic/studio#4908 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 90/100