| type | Reference | |||||
|---|---|---|---|---|---|---|
| title | OKF documentation and commit policy | |||||
| description | Canonical rules for durable vs ephemeral knowledge, commit messages, and post-update bundle consistency. | |||||
| tags |
|
|||||
| timestamp | 2026-07-31 00:00:00 UTC |
Single source of truth for OKF knowledge and commit wording. Other OKF docs/work queues link here; do not restate.
| Kind | Where it lives | What it contains |
|---|---|---|
| Durable | OKF reference docs (design, runbooks, registries, workflows) | Stable API names, module boundaries, SDK/tooling versions, verification methods, architecture, canonical commands |
| Ephemeral | Explicit work-queue docs only | Session phase/probe IDs, planned commit subjects (commit_subject), gate state, next_work_type, snapshot labels, dated banners, run counts |
Rules
- General OKF docs get durable only updates: no phase IDs, commit subjects, session test counts, or gate snapshots.
- Ephemeral state lives only in work queues. When an item closes, durable outcomes move to reference docs; queue rows may archive/delete.
- Durable docs may link to a work queue for current status; do not duplicate ephemeral fields.
We treat git commits as durable documentation: they are the canonical record of what changed, when, and why — for humans and agents reviewing history later, not only for the current PR thread.
Commit messages use Conventional Commits and describe durable product/process deliverables: what changed and why, not probe IDs, gates, test counts, or "phase X complete".
Common scopes in this repo (non-exhaustive): auth, database, firestore, storage, swiftui, ci, sample, docs, okf.
When a PR contains exactly one commit, the PR title must match that commit's subject line exactly (character-for-character). Multi-commit PRs use a summary title that describes the overall change set.
Also follow PULL_REQUEST_TEMPLATE.md and CONTRIBUTING.md (CLA, feature parity with FirebaseUI-Android where the change is user-facing).
OKF markdown edits require an independent bundle consistency pass. Use a fresh context with:
- A short summary of what changed and which files were touched.
- Instruction to scan the entire
okf-bundle/tree.
Confirm:
| Check | Requirement |
|---|---|
| Canonical location | Each topic has one owning doc; others link to it (agent command policy for all agent shell commands; change authoring for workflow/gates/frozen tree; change authoring § validation evidence (blocking); running tests for test command detail; iteration vocabulary for term ids only; change authoring § quality standards for review-findings resolution; coverage design for coverage expectations; SPM and CocoaPods workflow for distribution; firebase testing project for Auth emulator defaults; this file for doc/commit policy) |
| DRY | No duplicated procedures, policy paragraphs, or ephemeral snapshots outside work queues |
| Link hygiene | Cross-links resolve; indexes list canonical entry points |
| Durability | No ephemeral fields leaked into general reference docs |
Fix violations before handoff/merge. Work-queue edits still follow this split.
Work queues are intentionally ephemeral: phases, commit subjects, gates, active coordination. They are not policy or finalized registry/design homes.
Work queues record gates, next_work_type, validation_tier, and commit_subject using field names and allowed values from iteration vocabulary. Gate semantics and workflow rules: change authoring workflow. They do not name agent roles, dispatch instructions, or session choreography — those are out of scope for the public repo.
Record commit_subject (the planned Conventional Commit subject line) before git commit, in the same staged changeset as the item being memorialized. Do not record SHAs — they are unstable under history rewrite. After commit, the subject in git and in the queue must match character-for-character (PR title rule for single-commit PRs).
New work queues link here in frontmatter/opening section; do not copy policy inline.