|
| 1 | +// SPDX-License-Identifier: CC-BY-SA-4.0 |
| 2 | +// Relocated 2026-07-21 from rsr-julia-library-template-repo (its VARIANT.a2ml |
| 3 | +// lists it under paths.added). The document is explicitly language-agnostic |
| 4 | +// and belongs in the canon; the variant-side copy is retired separately. |
| 5 | += Universal Repo Standard (Must / Intend / Like) |
| 6 | + |
| 7 | +This document is designed as a reusable baseline for *every* repository (Julia and non-Julia). |
| 8 | +It combines dependability, security, accessibility, interoperability, functionality, performance, |
| 9 | +and data/information governance into one operational standard. |
| 10 | + |
| 11 | +Use this as: |
| 12 | + |
| 13 | +* A repo bootstrap checklist |
| 14 | +* A release-readiness checklist |
| 15 | +* A policy reference for CI/CD gates |
| 16 | + |
| 17 | +== Top-Level Principles (Apply To Every Repo) |
| 18 | + |
| 19 | +1. Dependability: deterministic behavior, graceful failure, and observable recovery. |
| 20 | +2. Security: secure-by-default design, supply-chain integrity, least privilege. |
| 21 | +3. Accessibility: inclusive UX and docs, equivalent access to critical workflows. |
| 22 | +4. Interoperability: stable contracts, versioned interfaces, compatibility guarantees. |
| 23 | +5. Functionality: features are complete, correct, and match documented claims. |
| 24 | +6. Performance: measurable baselines, regression protection, explicit budgets. |
| 25 | +7. Data/Information Governance: data classification, minimization, lineage, retention, and deletion controls. |
| 26 | + |
| 27 | +== Minimum Files In Every Repo |
| 28 | + |
| 29 | +Must include: |
| 30 | + |
| 31 | +* `README` (what it does, supported scope, quickstart, known limits) |
| 32 | +* `ROADMAP` (Must/Intend/Like or equivalent staged plan) |
| 33 | +* `CHANGELOG` (user-visible changes and migration impact) |
| 34 | +* `SECURITY.md` (reporting + hardening posture) |
| 35 | +* `LICENSE` |
| 36 | +* `CONTRIBUTING` (workflow and quality gates) |
| 37 | +* `CODEOWNERS` or `MAINTAINERS` |
| 38 | +* CI workflow(s) for test + lint + dependency/security checks |
| 39 | +* Reproducible dependency lock strategy (language-specific) |
| 40 | +* Operational runbook or `docs/ops` for incident response |
| 41 | + |
| 42 | +== MUST (Non-Negotiable Baseline) |
| 43 | + |
| 44 | +=== Dependability |
| 45 | + |
| 46 | +* No silent corruption or "fake" token values for critical outputs. |
| 47 | +* Explicit failure modes and fallback policy per critical path. |
| 48 | +* Health checks and structured diagnostics for runtime paths. |
| 49 | +* Fault counters (errors, fallbacks, recoveries) with alert thresholds. |
| 50 | +* Deterministic CI tests for happy path + failure path + fallback behavior. |
| 51 | + |
| 52 | +=== Security |
| 53 | + |
| 54 | +* Threat model exists and is reviewed periodically. |
| 55 | +* Secrets never committed; managed via secure runtime secret injection. |
| 56 | +* Dependency scanning + SAST + license checks in CI. |
| 57 | +* Signed releases/artifacts where supported. |
| 58 | +* Principle of least privilege for CI, runtime identities, and tokens. |
| 59 | + |
| 60 | +=== Containers And Images (High-Security Ready) |
| 61 | + |
| 62 | +* Pinned base images by digest; avoid floating tags in production. |
| 63 | +* Non-root runtime user; read-only root filesystem when possible. |
| 64 | +* Drop unnecessary Linux capabilities; avoid privileged containers. |
| 65 | +* SBOM generation + vulnerability scanning + policy gate. |
| 66 | +* Image signing and provenance attestation in release pipeline. |
| 67 | +* Explicit runtime constraints (seccomp/AppArmor/SELinux as applicable). |
| 68 | + |
| 69 | +=== Interoperability And API Contracts |
| 70 | + |
| 71 | +* Versioned API/ABI contracts with compatibility expectations. |
| 72 | +* Contract tests for REST/gRPC/GraphQL/FFI boundaries. |
| 73 | +* Backward-compatibility policy and deprecation lifecycle. |
| 74 | +* Clear error taxonomy (retryable vs non-retryable) and status semantics. |
| 75 | + |
| 76 | +=== Functionality And Correctness |
| 77 | + |
| 78 | +* Documentation claims must match tested behavior. |
| 79 | +* Acceptance tests for each "shipped" feature claim. |
| 80 | +* No unresolved critical work markers in production code paths. |
| 81 | +* Release checklist gates must pass before merge/release. |
| 82 | + |
| 83 | +=== Performance |
| 84 | + |
| 85 | +* Baseline benchmarks for critical operations and key backends. |
| 86 | +* Regression thresholds enforced in CI where baselines exist. |
| 87 | +* Performance evidence artifacts retained from CI runs. |
| 88 | +* Resource budgets (latency, memory, CPU, I/O) defined for critical flows. |
| 89 | + |
| 90 | +=== Data/Information Governance |
| 91 | + |
| 92 | +* Data classification policy (public/internal/confidential/restricted). |
| 93 | +* Data minimization and purpose limitation documented. |
| 94 | +* Retention and deletion policy documented and testable. |
| 95 | +* Audit trails for critical decisions and transformations. |
| 96 | +* Encryption requirements for data at rest/in transit documented. |
| 97 | + |
| 98 | +=== Accessibility |
| 99 | + |
| 100 | +* User-facing interfaces meet baseline accessibility criteria. |
| 101 | +* Docs include plain-language quickstarts and operational troubleshooting. |
| 102 | +* Keyboard-only and screen-reader considerations for web UI repos. |
| 103 | + |
| 104 | +== INTEND (Planned, High-Value Next Layer) |
| 105 | + |
| 106 | +=== Dependability |
| 107 | + |
| 108 | +* Circuit breakers and adaptive retry with backoff/jitter. |
| 109 | +* Chaos/fault-injection tests in non-production environments. |
| 110 | +* Automatic quarantine of persistently failing backends/providers. |
| 111 | +* Error budget policy tied to SLOs. |
| 112 | + |
| 113 | +=== Security |
| 114 | + |
| 115 | +* Mandatory security review for high-impact changes. |
| 116 | +* Ephemeral credentials and workload identity adoption. |
| 117 | +* Continuous policy-as-code validation (admission controls, OPA, etc.). |
| 118 | +* Signed commits/tags and stricter branch protection. |
| 119 | + |
| 120 | +=== Containers/Runtime |
| 121 | + |
| 122 | +* Distroless/minimal images for production workloads. |
| 123 | +* Runtime sandboxing for untrusted workloads. |
| 124 | +* Dedicated hardened node pools for sensitive workloads. |
| 125 | +* Provenance verification at deploy time. |
| 126 | + |
| 127 | +=== Interoperability |
| 128 | + |
| 129 | +* Multi-version compatibility test matrix (N-1, N, N+1 where applicable). |
| 130 | +* Golden test vectors for serialization/protocol compatibility. |
| 131 | +* SDK/client conformance tests against reference server behavior. |
| 132 | + |
| 133 | +=== Functionality |
| 134 | + |
| 135 | +* Formalized "definition of done" templates by feature type. |
| 136 | +* Auto-generated API docs from source contracts. |
| 137 | +* Domain-specific invariants/property tests. |
| 138 | + |
| 139 | +=== Performance |
| 140 | + |
| 141 | +* Automated trend dashboards with release-over-release comparisons. |
| 142 | +* Capacity modeling and saturation testing. |
| 143 | +* Hardware-specific tuning profiles validated by CI evidence. |
| 144 | + |
| 145 | +=== Data Governance |
| 146 | + |
| 147 | +* Data lineage map and classification tagging automation. |
| 148 | +* Policy checks that block non-compliant schema/data changes. |
| 149 | +* Differential privacy/redaction controls where needed. |
| 150 | + |
| 151 | +=== Accessibility |
| 152 | + |
| 153 | +* Automated accessibility checks in CI for UI repos. |
| 154 | +* Accessibility issue triage and SLA policy. |
| 155 | + |
| 156 | +== LIKE (Aspirational Or Context-Dependent) |
| 157 | + |
| 158 | +* Formal verification for high-assurance modules. |
| 159 | +* Multi-region active-active resilience for critical services. |
| 160 | +* Reproducible builds with full hermetic toolchains. |
| 161 | +* Runtime self-optimization under strict safety guards. |
| 162 | +* Advanced provenance federation across polyrepo ecosystems. |
| 163 | +* Organizational scorecards across all principles per repo. |
| 164 | + |
| 165 | +== Suggested CI Gates (Portable Template) |
| 166 | + |
| 167 | +Must gates: |
| 168 | + |
| 169 | +* Build + unit/integration tests |
| 170 | +* Contract tests (APIs/ABI/FFI) |
| 171 | +* Failure-mode and fallback tests |
| 172 | +* Lint/style/static checks |
| 173 | +* Vulnerability + license scans |
| 174 | +* Performance regression checks (where baseline exists) |
| 175 | +* Documentation claim alignment checks |
| 176 | + |
| 177 | +Evidence artifacts: |
| 178 | + |
| 179 | +* Test results |
| 180 | +* Security scan reports |
| 181 | +* Benchmark/performance evidence |
| 182 | +* Capability/diagnostic snapshots |
| 183 | +* SBOM + provenance attestations (release) |
| 184 | + |
| 185 | +== Practical Scope Control (To Avoid "Infinite Work") |
| 186 | + |
| 187 | +Apply this in tiers: |
| 188 | + |
| 189 | +1. Tier 1 (immediate): production-critical paths and externally exposed interfaces. |
| 190 | +2. Tier 2 (next): high-usage internal paths and integration boundaries. |
| 191 | +3. Tier 3 (later): low-risk or experimental components. |
| 192 | + |
| 193 | +Do not block all progress on full perfection. Gate by risk and blast radius. |
| 194 | + |
| 195 | +== Policy On Fallback Values |
| 196 | + |
| 197 | +For critical computation and security-sensitive flows: |
| 198 | + |
| 199 | +* Do not substitute dummy/token values silently. |
| 200 | +* Prefer: retry -> alternate backend/path -> explicit failure. |
| 201 | +* Every recovery or degradation event must be observable. |
| 202 | + |
| 203 | +For non-critical optional fields: |
| 204 | + |
| 205 | +* Defaults are acceptable only with clear provenance and policy. |
| 206 | + |
| 207 | +== How To Reuse In Other Repos |
| 208 | + |
| 209 | +Copy this file and then customize: |
| 210 | + |
| 211 | +* Language-specific tooling sections |
| 212 | +* API and data governance specifics |
| 213 | +* Backend matrix and performance budgets |
| 214 | +* Regulatory/compliance requirements |
| 215 | + |
| 216 | +Keep the principle set and Must baseline intact unless a stronger control replaces it. |
0 commit comments