|
| 1 | +--- |
| 2 | +type: Reference |
| 3 | +title: OKF documentation and commit policy |
| 4 | +description: Canonical rules for durable vs ephemeral knowledge, commit messages, and post-update bundle consistency. |
| 5 | +tags: [okf, documentation, policy, commits, work-queue] |
| 6 | +timestamp: 2026-07-31T00:00:00Z |
| 7 | +--- |
| 8 | + |
| 9 | +# OKF documentation and commit policy |
| 10 | + |
| 11 | +Single source of truth for OKF knowledge and commit wording. Other OKF docs/work queues link here; do not restate. |
| 12 | + |
| 13 | +## Durable vs ephemeral |
| 14 | + |
| 15 | +| Kind | Where it lives | What it contains | |
| 16 | +|------|----------------|------------------| |
| 17 | +| **Durable** | OKF reference docs (design, runbooks, registries, workflows) | Stable API names, module boundaries, SDK/tooling versions, verification **methods**, architecture, canonical commands | |
| 18 | +| **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 | |
| 19 | + |
| 20 | +**Rules** |
| 21 | + |
| 22 | +1. General OKF docs get **durable only** updates: no phase IDs, **commit subjects**, session test counts, or gate snapshots. |
| 23 | +2. Ephemeral state lives **only** in work queues. When an item closes, durable outcomes move to reference docs; queue rows may archive/delete. |
| 24 | +3. Durable docs may link to a work queue for current status; do not duplicate ephemeral fields. |
| 25 | + |
| 26 | +## Commits as documentation |
| 27 | + |
| 28 | +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. |
| 29 | + |
| 30 | +Commit messages use [Conventional Commits](https://www.conventionalcommits.org/) and describe durable product/process deliverables: what changed and why, not probe IDs, gates, test counts, or "phase X complete". |
| 31 | + |
| 32 | +Common scopes in this repo (non-exhaustive): `auth`, `database`, `firestore`, `storage`, `swiftui`, `ci`, `sample`, `docs`, `okf`. |
| 33 | + |
| 34 | +## Pull requests |
| 35 | + |
| 36 | +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. |
| 37 | + |
| 38 | +Also follow [`PULL_REQUEST_TEMPLATE.md`](../PULL_REQUEST_TEMPLATE.md) and [`CONTRIBUTING.md`](../CONTRIBUTING.md) (CLA, feature parity with FirebaseUI-Android where the change is user-facing). |
| 39 | + |
| 40 | +## OKF update contract |
| 41 | + |
| 42 | +OKF markdown edits require an **independent bundle consistency pass**. Use a fresh context with: |
| 43 | + |
| 44 | +1. A short summary of what changed and which files were touched. |
| 45 | +2. Instruction to scan the **entire** `okf-bundle/` tree. |
| 46 | + |
| 47 | +Confirm: |
| 48 | + |
| 49 | +| Check | Requirement | |
| 50 | +|-------|-------------| |
| 51 | +| **Canonical location** | Each topic has one owning doc; others link to it ([agent command policy](testing/agent-command-policy.md) for **all** agent shell commands; [change authoring](testing/change-authoring-workflow.md) for workflow/gates/frozen tree; [change authoring § validation evidence (blocking)](testing/change-authoring-workflow.md#validation-evidence-blocking); [running tests](testing/running-tests.md) for test command detail; [iteration vocabulary](testing/iteration-vocabulary.md) for term ids only; [change authoring § quality standards](testing/change-authoring-workflow.md#quality-standards) for review-findings resolution; [coverage design](testing/coverage-design.md) for coverage expectations; [SPM and CocoaPods workflow](packaging/spm-and-cocoapods-workflow.md) for distribution; [firebase testing project](testing/firebase-testing-project.md) for Auth emulator defaults; this file for doc/commit policy) | |
| 52 | +| **DRY** | No duplicated procedures, policy paragraphs, or ephemeral snapshots outside work queues | |
| 53 | +| **Link hygiene** | Cross-links resolve; indexes list canonical entry points | |
| 54 | +| **Durability** | No ephemeral fields leaked into general reference docs | |
| 55 | + |
| 56 | +Fix violations before handoff/merge. Work-queue edits still follow this split. |
| 57 | + |
| 58 | +## Work-queue documents |
| 59 | + |
| 60 | +Work queues are **intentionally ephemeral**: phases, **commit subjects**, gates, active coordination. They are not policy or finalized registry/design homes. |
| 61 | + |
| 62 | +Work queues record **gates**, **`next_work_type`**, **`validation_tier`**, and **`commit_subject`** using field names and allowed values from [iteration vocabulary](testing/iteration-vocabulary.md). Gate semantics and workflow rules: [change authoring workflow](testing/change-authoring-workflow.md). They do **not** name agent roles, dispatch instructions, or session choreography — those are out of scope for the public repo. |
| 63 | + |
| 64 | +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](#pull-requests) for single-commit PRs). |
| 65 | + |
| 66 | +New work queues link here in frontmatter/opening section; do not copy policy inline. |
0 commit comments