docs: document push-daemon-as-durability + fix stale PVC/working-tree language in runbook

Open Beginner friendly
#87 0 comments 0 reactions 0 assignees View on GitHub

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 once origin/<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/data inside 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from CodeForPhilly/codeforphilly-ng

All issues in CodeForPhilly/codeforphilly-ng

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.