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

@@ -29,8 +29,10 @@ restriction, or release gate mentioned in the templates.
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. Use
[agents/AGENTS.md](../agents/AGENTS.md) as the basis for the downstream root
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.
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
resulting local rules for consistency with the project's actual workflows.
@@ -41,6 +43,57 @@ 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.
```markdown
## Policy Reading Guide
| Policy | Read before… |
| --- | --- |
| [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.
```
## 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)
@@ -93,6 +146,32 @@ 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 for the review so later upstream changes do not shift 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. Do not
recommend wholesale replacement merely because upstream differs.
5. If a baseline is missing or unavailable, report the uncertainty. You may
compare available content, but do not assume the local policy is an unchanged
upstream copy or invent an adoption revision. If upstream cannot be reached,
report that limitation rather than claiming the policies are current.
For a recommendation-only request, leave files and adoption metadata unchanged.
A completed review does not mean a newer policy has been adopted. Apply the
following procedure when implementation is requested.
## Update Deliberately
Compare the previously recorded upstream files with a selected newer revision.