58 lines
3.2 KiB
Markdown
58 lines
3.2 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 examples illustrate downstream adoption.
|
|
|
|
## 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.
|
|
|
|
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. Diff, link, and example
|
|
review suffice 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. Use local links for new
|
|
assets until a containing commit is available. Confirm public reference links
|
|
are accessible when preparing publication of the reference changes.
|