policy/docs/adoption.md

Adopting And Updating The Policies

This guide is for agents and maintainers incorporating policies from Standard Repository Policies into another repository. This guide lives in the upstream repository; downstream projects link to it from their adopted docs/policy/meta.md. To edit the upstream templates themselves, use the contributor guide.

Downstream Files And Upstream References

Material	Downstream treatment
Applicable docs/policy/*.md, including meta.md	Copy and customize, retaining each document's upstream provenance.
agents/AGENTS.md	Adapt into the downstream root AGENTS.md.
Downstream docs/development.md	Create or update for that project using the reading guidance below.
This repository's README, root AGENTS.md, developer guide, and adoption guide	Keep upstream and consult through links as needed.
Licensing examples	Reference upstream and use them to create actual project notices.
Applicable standard license texts	Copy locally as specified below and in the OSS policy.

Select A Baseline

Select an upstream commit and read the policies relevant to the requested work. Use a revision containing the project grant and the reference assets you intend to use. Record its full commit identifier as the adoption baseline. Git records are sufficient to maintain adoption provenance.

Preserve existing downstream decisions and unrelated changes. Customize selected policies to existing project responsibilities and the author's requested scope.

Copy And Customize

1. Copy docs/policy/meta.md and the applicable policy documents to the same downstream locations. Follow each template's adoption instructions and remove its Base Policy Template section afterward. Create supporting documents when they have useful content for an existing responsibility.
2. Tailor architecture to the actual project. Preserve the author's selected license and existing application contracts.
3. Retain each document's Base Policy Version and set Last Updated to the local adoption date. Add Upstream Source metadata linking to that specific document at the selected commit. Retain this provenance in future edits.
4. Create or update the downstream docs/development.md reading guide, including the policy reading guide below, which routes adoption and update tasks to policy/meta.md. Use agents/AGENTS.md as the basis for the downstream root AGENTS.md, merging its orientation links with existing instructions.
5. Add the attribution and document-license scope described below. Review the resulting local rules for consistency with the project's actual workflows.

A source link has this shape; substitute the selected full commit and filename:

https://gitea.maximumdirect.net/eric/policy/src/commit/UPSTREAM_COMMIT/docs/policy/testing.md

Set Up Selective Policy Reading

Include the following in the downstream docs/development.md, merging it with existing reading guidance and retaining rows for the policies adopted locally. The links are relative to that downstream document. Keep policy reading triggers there; the documentation policy remains the owner of the documentation topic map.

## Policy Reading Guide

| Policy | Read before… |
| --- | --- |
| [Policy set provenance](policy/meta.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.

Attribute Copied Policies

Use the canonical attribution entry by inserting it beneath the existing title in the downstream docs/oss/attribution.md.

• Replace UPSTREAM_COMMIT with the selected full commit in all three URLs.
• Adjust the Material: sentence to identify the files actually copied. Keep “adapted for this repository” for customized documents; use “copied without modification” for unchanged copies. For a mixture, identify which are adapted.
• Preserve supplied creator, copyright, license, and warranty-disclaimer notices, including the link to upstream COPYRIGHT. Retain indications of prior modifications as the documents evolve.
• Copy CC-BY-SA-4.0.txt into the downstream docs/oss/licenses/. The entry's relative license link assumes that location.

This entry is the project's recommended attribution arrangement for copied or adapted policies. Its short material statement identifies scope and modification status; do not add research narratives or compliance commentary.

Keep customized policy documents under CC-BY-SA 4.0 in this standard adoption workflow. Identify that scope in the downstream COPYRIGHT, for example:

Policy documents adapted from Standard Repository Policies remain licensed
under CC-BY-SA-4.0. See docs/oss/attribution.md for the affected material,
upstream credit, and license links.

The application's own code retains its selected license. Copying a policy does not select a new license for unrelated code or documentation. These instructions implement the project grant; they do not add a requirement to publish private work or send modifications upstream. Other arrangements permitted by the license remain available.

Use Reference Assets

Create actual COPYRIGHT and attribution files using the upstream application, library, and attribution examples. Read the OSS policy for their format and placeholder substitution rules. Original example formatting is available under CC0 as specified in COPYRIGHT; using that formatting alone does not require an attribution entry for this project.

Keep links to these examples in the adopted policy pointed at upstream commits. Keep the example collection upstream and use it to create actual project notices. Copy the applicable standard license texts into the actual local license files; retain their wording and their own terms. Those copies remain necessary under the House Format even though example documents stay upstream.

Check For Upstream Revisions

When asked to check the policy set and recommend updates:

1. Read the local policies and identify each document's Upstream Source commit, Base Policy Version, and local customizations. Different documents may have different adoption baselines.
2. Inspect upstream main and record its full commit identifier. Use that fixed revision throughout the comparison.
3. Compare each recorded upstream file with its counterpart at the review revision, then assess the upstream changes against the locally customized policy. Version labels help orientation; inspect the actual differences. Note new, renamed, or removed upstream policies where relevant to the project.
4. Recommend applicable changes with their reasons, identify conflicts with deliberate local choices, and name policies that need no update. Include the baseline and review revisions so the comparison can be reproduced. Ground recommendations in the local project's needs.
5. Base provenance claims on available evidence. Report missing or unavailable baselines explicitly and qualify comparisons accordingly. Report upstream access failures and the resulting limits on the review.

For a recommendation-only request, preserve the current files and adoption metadata. Apply the following procedure when implementation is requested.

Update Deliberately

Compare the previously recorded upstream files with a selected newer revision. Apply relevant changes while preserving local decisions and selecting updates that serve the project.

Update Base Policy Version when adopting a newer template version and update Upstream Source to the revision actually incorporated. Change Last Updated when revising the local document. Keep the material description, modification status, and attribution links accurate. If documents use different upstream revisions, retain each file's exact source metadata and include the necessary commit-specific source and notice links in the single project attribution entry.

Ordinary review should check the resulting rules, attribution facts, and affected links. A commit-based adoption record is sufficient; no recurring synchronization check, release gate, or separate license approval is required. Agents following this documented arrangement need additional clarification only for a concrete circumstance it does not cover. User instructions govern whether changes are committed or published.