62 lines
3.5 KiB
Markdown
62 lines
3.5 KiB
Markdown
# Developing Standard Repository Policies
|
|
|
|
This repository maintains reusable policy templates and reference materials.
|
|
For adopting them into another project, use the [adoption guide](adoption.md).
|
|
|
|
## Orientation
|
|
|
|
Read the [agent policy](policy/agents.md) and inspect the working tree before
|
|
editing. Preserve unrelated work. Follow explicit task instructions, including
|
|
requests to leave changes uncommitted. This repository's policy files retain
|
|
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.
|
|
|
|
## Policy Reading Guide
|
|
|
|
| Policy | Read before… |
|
|
| --- | --- |
|
|
| [Adoption and update guide](adoption.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
|
|
| [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.
|
|
- Select policies using the task triggers above. Follow cross-references to
|
|
relevant sections 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
|
|
|
|
Keep reusable instructions portable. Put adoption instructions in template
|
|
sections and project-specific contributor procedures here. Original licensing
|
|
examples belong under `examples/licensing/`; explanatory instructions belong in
|
|
their guide or policy so they are not copied into notices.
|
|
|
|
Increment the affected template's `Base Policy Version` and update its date when
|
|
changing its substantive rules or adoption instructions. Preserve the licensing
|
|
scope defined in `COPYRIGHT`; reproduced license texts must remain verbatim.
|
|
|
|
Review the diff, run `git diff --check` for changed prose, and check affected links
|
|
and examples. Example placeholders and destination-relative links should be
|
|
validated against the documented downstream layout, not treated as published
|
|
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 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.
|