docs: establish ZitPlane notes project and user documentation governance
This commit is contained in:
1 parent
40af500750
commit
7ecf531697
22 files changed
+1507
No files matched your search
@@ -25,3 +25,30 @@
|
||||
## Developer experience
|
||||
- Keep README files accurate for the current phase. Do not claim an app runs before it is integrated.
|
||||
- Develop on local/test ZITADEL and synthetic users. Verify OIDC, MFA/passkey and redirect flows before release.
|
||||
|
||||
|
||||
## Documentation-first rule — mandatory for ALL future changes
|
||||
|
||||
Three distinct Git-tracked knowledge areas are required and must stay synchronized:
|
||||
|
||||
1. **`notes/` — development-time scope, planning and phase history.** Before ANY code/config/page/feature/fix/add/remove/refactor (including documentation changes), first write or update a scoped Markdown plan there. State baseline, date, goals, exact allowed paths, exclusions, intended changes, prerequisites, risk and acceptance criteria. Keep in-progress decision log, source evidence, blockers and after-action result. Every update/fix/phase needs a dated entry in `notes/CHANGELOG.md`; do not delete historic outcomes.
|
||||
2. **`project/` — permanent developer/AI reference.** In the same approved phase, update exact developer descriptions of EVERY affected feature/page/module/file/function, logic location and rationale, dependencies and setup, API/data/security flow, tests/evidence and change history. Maintain `project/FILE-MAP.md`, `project/FUNCTIONS.md`, `project/FEATURES-AND-PAGES.md`, `project/SETUP-AND-DEPENDENCIES.md`, `project/CHANGELOG.md`, and `project/SOURCE-INVENTORY.md` where relevant. Describe unchanged source only when actually inspected; never fabricate behavior.
|
||||
3. **`docs/` — permanent end-user/operator guidance.** In the same approved phase, document every changed accessible page, button/action, route, feature, permission, setup step, failure case, security or usage limitation in plain, beginner-friendly instructions. Update `docs/USER-GUIDE.md`, `docs/SETUP-GUIDE.md`, `docs/FEATURES-STATUS.md`, `docs/TROUBLESHOOTING.md` and existing focused guides as applicable. Never advertise incomplete source as tested or deployed.
|
||||
|
||||
### Mandatory Markdown and manifest policy
|
||||
|
||||
- Every **new ZitPlane-owned folder**, including each knowledge-area folder and newly created subfolder, must include its own `README.md` describing **why it exists, who uses it, when/how to update it**, and literal **`MINIFEST.md`** listing its actual direct files/subfolders, owners/purposes, phase and status. The exact filename is `MINIFEST.md` (not `MANIFEST.md`).
|
||||
- When a first-party file/folder is added, moved or removed, update the relevant parent `MINIFEST.md`, root navigation and source inventory in the same phase. Do not include ignored/generated data in Git manifests as if tracked.
|
||||
- **Do not edit third-party/upstream/vendor-imported source** (such as nested `auth/ui/v2/apps/login/`, `packages/` or `proto/`) just to inject ZitPlane docs. Preserve upstream byte-for-byte identity and document their paths in `project/SOURCE-INVENTORY.md`; only modify upstream content with explicit scope and license review.
|
||||
- For preexisting first-party directories not changed in the current phase, add missing per-folder guidance when an approved phase next modifies their structure. Knowledge-area folders `notes/`, `project/`, `docs/` are mandatory immediately.
|
||||
- `README.md` is the human-friendly entrypoint; `MINIFEST.md` is the exact direct-child inventory; avoid duplicating long feature explanations across both.
|
||||
|
||||
### Every change must leave a consistent audit trail
|
||||
|
||||
**Before:** audit Git status/current source, create `notes/<PHASE>.md` scope/plan, and confirm approval.
|
||||
|
||||
**During:** keep a concise change/decision log and identify each touched function/page/file and user-facing consequence.
|
||||
|
||||
**After:** update relevant `project/` and `docs/` files plus manifests, record exact implementation/test/CI results, commit SHA and residual risk in `notes/` and `project/CHANGELOG.md`. Perform one focused scope/patch audit and commit as approved. Do **not** say a CI/build/runtime test passed unless it actually ran.
|
||||
|
||||
**Safety:** Never write passwords, personal data, .env contents, secrets, PATs, credentials, private keys or unredacted token-bearing logs into any `notes/`, `project/` or `docs/` Markdown file. Do not expand source write scope simply to satisfy documentation; obtain separate approval if necessary. Remote push/deploy still requires explicit approval.
|
||||
Reference in new issue
Block a user