eric/policy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clarify downstream policy files and upstream references

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-27 19:14:00 +00:00
parent 027604e974
commit 04e20af744
5 changed files with 60 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/adoption.md
View File

@@ -2,8 +2,20 @@
This guide is for agents and maintainers incorporating policies from
[Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy)
into another repository. To edit the upstream templates themselves, use the
[contributor guide](development.md).
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](development.md).
## 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
@@ -19,7 +31,8 @@ restriction, or release gate mentioned in the templates.
## Copy And Customize
1. Copy applicable documents from `docs/policy/` to the same downstream location.
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, rather than filling an empty outline.
@@ -30,8 +43,8 @@ restriction, or release gate mentioned in the templates.
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](#set-up-selective-policy-reading) and
[policy-update discovery section](#make-upstream-updates-discoverable) below.
the [policy reading guide](#set-up-selective-policy-reading) below, which routes
adoption and update tasks to `policy/meta.md`.
Use [agents/AGENTS.md](../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
@@ -55,6 +68,7 @@ there; the documentation policy remains the owner of the documentation topic map
| 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. |
@@ -64,9 +78,8 @@ there; the documentation policy remains the owner of the documentation topic map
- 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.
- 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.
@@ -74,26 +87,6 @@ there; the documentation policy remains the owner of the documentation topic map
affected by the revision.
```
## Make Upstream Updates Discoverable
Include this section in the downstream `docs/development.md`, merging it with
existing update guidance where appropriate:
```markdown
## Policy Updates
These policies derive from
[Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy).
When asked to check for upstream revisions, follow its
[adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
Each adopted policy records its baseline in `Upstream Source`.
```
The repository and current-guide links enable discovery of newer revisions.
Keep these discovery links pointed at the current upstream project; retain
commit-pinned links for adopted source baselines and reference examples. This
provides an on-request workflow, without automated polling or a release gate.
## Attribute Copied Policies
Use the [canonical attribution entry](../examples/licensing/policy-attribution.md)