Clarify policy reading and upstream update guidance

This commit is contained in:
2026-09-27 19:07:05 +00:00
parent 1be7cab839
commit 027604e974
4 changed files with 113 additions and 14 deletions

View File

@@ -12,12 +12,27 @@ their template adoption sections because they are distributed as templates.
Application-specific template examples do not require this repository to acquire
application interfaces or infrastructure.
| Task | Read |
## Policy Reading Guide
| Policy | Read before… |
| --- | --- |
| Change a policy | The affected policy, its related policies, and the [documentation policy](policy/documentation.md). |
| Change adoption or provenance guidance | The [adoption guide](adoption.md), [OSS policy](policy/oss.md), and root [COPYRIGHT](../COPYRIGHT). |
| Change licensing examples | The [OSS policy](policy/oss.md), [COPYRIGHT](../COPYRIGHT), and affected examples. |
| Add or update reference license texts | The [reference collection README](oss/licenses/README.md) and the selected publisher or recorded upstream source. |
| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
| [Architecture](policy/architecture.md) | Planning or changing application code or its structure. |
| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
| [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. |
- Read applicable policies before making decisions they govern; multiple policies
may apply.
- Do not read the entire suite by default or recursively follow every
cross-reference. Read relevant sections of supporting references when needed
to resolve a concrete question.
- Reuse policies already available in context; reread when changed or no longer
available.
- Expand reading when the task's scope expands.
- When revising a policy itself, read that policy and any provisions elsewhere
affected by the revision.
## Editing And Validation
@@ -37,8 +52,10 @@ URLs or missing local dependencies. No application build or new test suite is
needed for prose-only changes. Retain upstream formatting in verbatim license
texts even where it would trigger whitespace warnings.
Pin upstream reference links to commits that contain the referenced files. New
assets can use local links within this repository until a containing commit is
available; do not invent a future hash or publish changes merely to obtain one.
Pin adopted-source and example links to commits that contain the referenced
files. Discovery links to the upstream project and current adoption guide may
track `main` so downstream agents can find updates. New assets can use local
links within this repository until a containing commit is available; do not
invent a future hash or publish changes merely to obtain one.
Before publication, confirm that public reference links are accessible. This is
change validation, not a recurring downstream release gate.