Expand roadmap to align the full policy set
This commit is contained in:
@@ -1,196 +1,208 @@
|
||||
# Align Licensing Documentation With the Standard Policy
|
||||
# Align Narratio With Standard Repository Policies
|
||||
|
||||
Status: Accepted; implementation pending.
|
||||
|
||||
## Goal
|
||||
## Goal and Approved Scope
|
||||
|
||||
Adopt the agreed licensing-documentation conventions without changing
|
||||
Narratio's license, runtime behavior, or release responsibility boundary. Make
|
||||
project licensing and upstream attribution easy to find and maintain through
|
||||
ordinary development and release preparation.
|
||||
Align Narratio's adopted policy language with Standard Repository Policies.
|
||||
Use upstream wording verbatim for non-substantive differences. Retain variations
|
||||
only for substantive, locally significant requirements or decisions and explain
|
||||
their justification. Follow template adoption instructions and customize required
|
||||
project-specific sections rather than copying instructional placeholders.
|
||||
|
||||
This roadmap defines the target and scope, not implementation sequencing.
|
||||
This document defines the target and scope, not implementation stages. It
|
||||
supersedes the earlier licensing-only roadmap: public upstream discovery,
|
||||
copied-policy attribution, and coordinated release-workflow alignment are now
|
||||
included. The earlier prohibition on policy-project references and deferral of
|
||||
broader release alignment no longer apply.
|
||||
|
||||
## Current Baseline
|
||||
## Fixed Review Revision and Baseline
|
||||
|
||||
The agreed house conventions cover project licensing, component attribution,
|
||||
and README/release navigation. Policy templates are internal administrative
|
||||
material, not an attribution source. Do not cite or link their repository,
|
||||
filesystem location, or contents in Narratio documentation. Adopted policies
|
||||
must be self-contained; license texts and component notices must trace to their
|
||||
actual public publishers and upstream projects.
|
||||
The approved review compared current local documents directly with upstream
|
||||
commit `d84a38ebab26f048cafbe59a2246700c35d29843`, verified against published
|
||||
`main` on 2026-09-28. Historical adoption baselines need not be reconstructed.
|
||||
Do not imply that this revision was previously adopted.
|
||||
|
||||
Narratio currently has:
|
||||
Follow the [adoption guide at the reviewed revision](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md).
|
||||
Use this fixed revision for implementation; incorporating a later revision
|
||||
requires deliberate comparison rather than an implicit refresh.
|
||||
|
||||
- A root `COPYRIGHT` identifying Narratio, its copyright holder, and the
|
||||
`GPL-3.0-or-later` grant, warranty disclaimer, and third-party-material caveat.
|
||||
- A complete root `LICENSE` matching the standard GPLv3 text except
|
||||
for a missing final newline. No substantive licensing correction is needed.
|
||||
- Documentation policy based on v1.1, without the new licensing ownership map,
|
||||
and no `docs/policy/oss.md` or `docs/oss/` attribution collection.
|
||||
- A README without the prescribed closing license and attribution navigation.
|
||||
- Release policy and procedure without the new licensing footer convention.
|
||||
The existing Woodpecker publisher already uses the matching checked-in release
|
||||
document as the hosted Gitea release body.
|
||||
Narratio has five adopted policies without per-document Upstream Source links.
|
||||
It lacks `docs/policy/meta.md`, `docs/policy/oss.md`, and the OSS attribution
|
||||
collection. Its development guide has task routes but not the standard selective
|
||||
policy-reading guidance. COPYRIGHT already grants GPL-3.0-or-later and LICENSE
|
||||
contains GPLv3; only the separate policy-document licensing scope needs adding.
|
||||
|
||||
Narratio publishes source and tagged Linux amd64/arm64 and best-effort macOS
|
||||
arm64 binaries with checksums. Successful publication of the intended tag to
|
||||
`origin` remains the release command's responsibility boundary; asset publication
|
||||
is asynchronous. The current dependency graph includes ConfigKit, AWS modules,
|
||||
Go extension packages, YAML libraries, and test dependencies. This roadmap does
|
||||
not claim that their individual terms or attribution coverage have been audited.
|
||||
The release process already ends at successful tag publication to `origin`, uses
|
||||
lightweight tags and source-push-before-tag, and publishes Gitea binaries and
|
||||
checksums asynchronously. Current guidance requires standalone validation before
|
||||
publication repeats it. The checker requires fixed note sections and repeats
|
||||
documentation/example tests included in the full suite. These are alignment
|
||||
work, not automatic justifications for different policy language.
|
||||
|
||||
ConfigKit is now selected at v0.4.1, whose patch contains licensing/documentation
|
||||
changes only. Its project grant is LGPL-3.0-or-later and its LICENSE includes
|
||||
both LGPLv3 and GPLv3. PromptKit v0.11.1 likewise updates licensing documentation
|
||||
and selects MIT-licensed catalog releases, but is not in Narratio's Go module
|
||||
graph. Its use by separately installed downstream applications does not make it
|
||||
a Narratio dependency or justify adding it to this inventory by itself.
|
||||
## Policy Target
|
||||
|
||||
## Targeted End State
|
||||
| Document | Target version | Required treatment |
|
||||
| --- | --- | --- |
|
||||
| `docs/policy/agents.md` | 1.3 | Adopt upstream wording. Remove redundant general-purpose local elaborations; retain application safeguards in architecture. Existing local-commit behavior remains. |
|
||||
| `docs/policy/testing.md` | 1.3 | Adopt upstream wording after template removal. Protect requested behavior and established contracts without turning risk categories or examples into new requirements. No local exception is needed. |
|
||||
| `docs/policy/documentation.md` | 1.11 | Adopt general wording and customize the ownership table. Retain troubleshooting ownership and materially useful stage/integration terminology; omit inapplicable public HTTP/API responsibilities. Add provenance and licensing owners. |
|
||||
| `docs/policy/architecture.md` | 1.3 | Adopt general framing and customize application-specific sections as instructed. Preserve Narratio's established contracts rather than substituting generic examples. |
|
||||
| `docs/policy/release.md` | 1.4 | Adopt upstream wording with coordinated executable changes. Tag-push completion and authoritative-remote scope are now standard, not local exceptions requiring compensating controls. |
|
||||
| `docs/policy/meta.md` | 1.0 | Add local authority, public discovery, adoption-guide navigation, and per-document provenance guidance. |
|
||||
| `docs/policy/oss.md` | 1.8 | Add current House Format, copied-document treatment, maintenance, and reference-example links; customize project/distribution facts. |
|
||||
|
||||
The existing project grant remains unchanged. A tailored OSS policy governs
|
||||
licensing documentation, and a canonical attribution inventory accurately
|
||||
describes material incorporated into or distributed with Narratio. Applicable
|
||||
standard texts are available locally; project-specific upstream notices and
|
||||
source links identify the actual imported commits.
|
||||
No existing policy is wholly unchanged because provenance and wording require
|
||||
updates. Narratio's architectural decisions and agent commit behavior need no
|
||||
substantive change. Wording preferences alone do not justify local variants.
|
||||
|
||||
README and future release documents navigate to these canonical materials.
|
||||
Contributors can discover the policy from the development guide and maintain
|
||||
attribution in the same change as the relevant dependency or distribution change.
|
||||
There is no duplicate inventory, new licensing service, or additional release
|
||||
approval system.
|
||||
## Provenance and Orientation
|
||||
|
||||
## Required Changes
|
||||
Remove each adopted document's `Base Policy Template` section and replace other
|
||||
template-only guidance with substantive project content where required. Retain
|
||||
the actual Base Policy Version, set Last Updated to the adoption date, and add
|
||||
Upstream Source pointing to that individual file at the reviewed commit:
|
||||
|
||||
### Adopt a Tailored OSS Policy
|
||||
```text
|
||||
https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILE.md
|
||||
```
|
||||
|
||||
Add `docs/policy/oss.md` using the agreed OSS conventions, retaining its base version
|
||||
and recording the adoption date. Remove template instructions and adapt links
|
||||
that point to template-only examples or reference collections. Do not introduce
|
||||
placeholder documents merely to satisfy those links.
|
||||
Substitute the correct filename for each policy. Preserve accurate provenance in
|
||||
later edits; Git records suffice without a new adoption registry or sync service.
|
||||
|
||||
Identify Narratio's existing application license and connect the policy to the
|
||||
canonical repository and release documentation for its Gitea host, distribution
|
||||
channels, and publication mechanism. Preserve the author's license choice;
|
||||
adoption is not relicensing. Leave COPYRIGHT and LICENSE substantively intact;
|
||||
normalizing the final newline is optional formatting only.
|
||||
Adapt upstream `agents/AGENTS.md` into root `AGENTS.md`, preserving applicable
|
||||
existing instructions. Do not copy upstream's root agent instructions, which
|
||||
govern work on that repository. Incorporate the supplied selective Policy Reading
|
||||
Guide into `docs/development.md`: select by task, read before governed decisions,
|
||||
reuse available context, follow relevant cross-references, expand reading when
|
||||
scope expands, and read affected provisions when revising policies. Do not make
|
||||
reading the whole suite mandatory. Preserve useful Narratio-specific task routes.
|
||||
|
||||
Retain the agreed House Format and settled interpretation of notice links:
|
||||
project-specific license and attribution material is linked at its imported
|
||||
commit rather than copied locally solely because its terms use reproduction,
|
||||
inclusion, or copy language. This convention does not establish license
|
||||
compatibility or discharge distinct obligations such as modified-file notices
|
||||
or corresponding source. Preserve required notices in incorporated source.
|
||||
Record concrete obligations or unresolved rights questions outside the format
|
||||
with their reason and selected treatment; do not invent exceptions based on
|
||||
common ownership or require repeated approval of the settled convention.
|
||||
Meta links to the [public project](https://gitea.maximumdirect.net/eric/policy)
|
||||
and [current adoption guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
|
||||
These are current-discovery links; adopted-source and example links stay
|
||||
commit-pinned. Reading triggers belong in development guidance and formal credit
|
||||
in attribution, not duplicated in meta.
|
||||
|
||||
### Establish Canonical Ownership and Contributor Routing
|
||||
## Justified Local Customizations
|
||||
|
||||
Incorporate the agreed licensing ownership additions into
|
||||
`docs/policy/documentation.md`, preserving Narratio-specific ownership
|
||||
and existing unrelated decisions. Clearly assign:
|
||||
Preserve established stage/adapter boundaries, manifest-driven resume/restore,
|
||||
artifact/path contracts, publication and lock semantics, credential protections,
|
||||
group-owned workspace behavior, and platform support. These express Narratio's
|
||||
operational responsibilities; policy alignment does not authorize changing them.
|
||||
|
||||
- Project identity, copyright, and grant to `COPYRIGHT`.
|
||||
- Complete project license text to `LICENSE`.
|
||||
- General licensing and attribution conventions to `docs/policy/oss.md`.
|
||||
- Component-specific attribution to `docs/oss/attribution.md`.
|
||||
- Verbatim standard dependency license texts to `docs/oss/licenses/`.
|
||||
- Navigation to README and release notes; concrete release URL construction
|
||||
and publication mechanics to `docs/release.md`.
|
||||
Retain Linux amd64/arm64 and best-effort macOS arm64 deliverables, without new
|
||||
native-platform gates or Windows/Intel Mac support. Preserve `origin/main`,
|
||||
lightweight tags, and source-push-before-tag in the release procedure. These are
|
||||
permitted project-specific mechanics, not exceptions to tag-push completion.
|
||||
|
||||
Record the selective policy update accurately; do not imply unrelated policy
|
||||
changes have been adopted by merely changing version metadata.
|
||||
Add a task-specific reading route in `docs/development.md` for licensing,
|
||||
dependency, attribution, and release-document changes. Avoid repeating the OSS
|
||||
rules in the agent, architecture, or testing policies.
|
||||
Customize documentation ownership for real Narratio interfaces and responsibilities,
|
||||
including troubleshooting; do not create empty API/consumer documents. Keep common
|
||||
prose verbatim around these customizations and explain substantive local choices
|
||||
in their canonical owner rather than maintaining a parallel general policy essay.
|
||||
|
||||
### Establish the Attribution Inventory
|
||||
## Licensing, Attribution, and Local Materials
|
||||
|
||||
Review actual incorporated and distributed material, including relevant
|
||||
transitive dependencies, Go runtime material in binaries, and copied code or
|
||||
assets. Use the selected source revisions and actual use/distribution to decide
|
||||
coverage, not just direct entries in `go.mod`. Neither every development tool
|
||||
nor every separately installed subprocess application automatically belongs in
|
||||
the inventory. Review any such component if Narratio actually incorporates or
|
||||
distributes it.
|
||||
Create `docs/oss/attribution.md` with the prescribed title followed directly by
|
||||
factual component entries. Use the canonical Standard Repository Policies entry
|
||||
from the reviewed commit. Identify actual copied/adapted material, including policy
|
||||
files, adapted agent instructions, and copied reading-guide material as applicable.
|
||||
Preserve creator, copyright, license, disclaimer, and modification notices. Pin
|
||||
source, COPYRIGHT, and LICENSE links to the reviewed full commit.
|
||||
|
||||
Create `docs/oss/attribution.md` with the agreed five-field format: project
|
||||
name, faithful upstream copyright statements, applicable SPDX expression,
|
||||
license/notice links, and a source repository link. Preserve multiple statements,
|
||||
licensing alternatives, versions, and exceptions where applicable. Do not infer
|
||||
ownership or invent identifiers; identify nonstandard terms through their texts.
|
||||
Copy CC-BY-SA-4.0 into `docs/oss/licenses/`. Add the limited policy-document scope
|
||||
to COPYRIGHT with an attribution link: adapted policy material remains CC-BY-SA-4.0;
|
||||
Narratio's application code remains GPL-3.0-or-later. Root LICENSE needs no
|
||||
replacement. Original upstream licensing-example formatting is CC0 and alone
|
||||
does not require attribution.
|
||||
|
||||
Resolve source and notice links to the exact imported commit, including for
|
||||
copied material. Version tags and moving branches are not substitutes for those
|
||||
component commit links. Inspect the selected source's license and notices rather
|
||||
than assuming terms from a dependency name or current upstream main branch.
|
||||
Complete the previously agreed inventory of incorporated/distributed material:
|
||||
relevant transitive dependencies, Go runtime material in shipped binaries, and
|
||||
copied code, documentation, or assets. Inspect selected sources and actual use;
|
||||
neither direct dependencies alone nor every development tool defines scope.
|
||||
ConfigKit v0.4.1 is a dependency. PromptKit is not in Narratio's module graph;
|
||||
invoking a separately installed downstream application does not itself incorporate
|
||||
that application's dependencies into Narratio.
|
||||
|
||||
Copy only the applicable complete, unmodified standard texts into
|
||||
`docs/oss/licenses/`. Reuse a text across entries where appropriate, but preserve
|
||||
distinct versions and exceptions. Make required companion texts directly
|
||||
reachable from the affected entry; LGPLv3, if applicable, includes GPLv3.
|
||||
Classify upstream files by content, not filename: a LICENSE file containing
|
||||
project-specific notices may require both its upstream link and a local standard
|
||||
text link. Keep explanatory prose outside the verbatim texts.
|
||||
Follow OSS v1.8's ordered fields and presentation: project heading, applicable
|
||||
faithful copyright statements, applicable SPDX expression, license/notice links,
|
||||
and a link labeled `Source` to the exact commit, ending with a period.
|
||||
Optional identification remains factual. Preserve
|
||||
alternatives, exceptions, and required notices; do not invent identifiers or add
|
||||
research narratives, compliance conclusions, or exception reasoning to entries.
|
||||
|
||||
### Add README and Release Navigation
|
||||
Copy applicable complete standard texts locally and make companion texts directly
|
||||
reachable. Link project-specific notices and sources at exact imported commits,
|
||||
not moving branches or tags. Apply the House interpretation of notice links
|
||||
without blanket additional local-copy requirements. Distinct concrete obligations
|
||||
still receive appropriate treatment; preserve notices in incorporated source.
|
||||
|
||||
End README with two friendly statements linking to the existing GPL v3-or-later
|
||||
grant in COPYRIGHT and the new attribution document.
|
||||
Keep upstream's README, root AGENTS.md, development/adoption guides, and example
|
||||
collection upstream. Retain commit-pinned example links in the adopted OSS policy;
|
||||
create actual local notices instead of copying the example collection. Adopted
|
||||
policies, project orientation, actual attribution, and applicable standard texts
|
||||
belong locally. Do not create placeholders for template-only links.
|
||||
|
||||
Update `docs/policy/release.md` to reference the OSS footer convention, and
|
||||
`docs/release.md` to give the concrete Narratio Gitea URL construction. Each new
|
||||
release document and its hosted download page must end with three links whose
|
||||
visible text is `COPYRIGHT | LICENSE | ATTRIBUTION`. Use absolute URLs at that
|
||||
release's immutable tag or corresponding immutable source revision. Unlike
|
||||
upstream component links, these release-navigation links may use the release tag.
|
||||
End README with the prescribed grant and attribution links. Future release notes
|
||||
and hosted pages end with `COPYRIGHT | LICENSE | ATTRIBUTION` links at their
|
||||
immutable release tag or source revision. The procedure owns concrete Gitea URLs;
|
||||
continue using the checked-in note as the hosted body. Maintain attribution with
|
||||
relevant dependency/material changes through ordinary review.
|
||||
|
||||
Retain reuse of the checked-in release note by `.woodpecker/release.yml`; no new
|
||||
publisher is expected. Prepare the footer alongside the note and verify its
|
||||
intended paths against the candidate source. A future tag need not already
|
||||
resolve remotely. Do not add publication-time network checks or CI polling.
|
||||
## Coordinated Release Alignment
|
||||
|
||||
### Keep Ongoing Maintenance Proportionate
|
||||
Update release policy, `docs/release.md`, relevant scripts, tests, and development
|
||||
guidance together so rules and executable behavior agree:
|
||||
|
||||
Update affected entries, source/notice commit links, and texts in changes that
|
||||
add, remove, upgrade, copy, or alter distribution of relevant components. Review
|
||||
faithful license text copies, statements, and destinations through ordinary
|
||||
change review and existing local documentation checks.
|
||||
- Make publication the normal validating-and-publishing entry point. Standalone
|
||||
validation remains optional rather than a mandatory duplicate prior pass.
|
||||
- Remove fixed release-note section requirements. Preserve version-matched notes
|
||||
and titles, relevant compatibility/upgrade information, and the licensing footer.
|
||||
- Remove duplicate documentation/example test invocations covered by the full
|
||||
suite. Avoid repeated validation of the same final candidate; no persistent
|
||||
validation cache is required.
|
||||
- Select additional gates by concrete risk and distinct protection. Do not keep
|
||||
race, static, module-hygiene, formatting, or other checks merely because they
|
||||
exist; document reasons for retained checks. Do not remove useful checks merely
|
||||
to minimize command count. Resolve the exact set during implementation planning
|
||||
against these criteria rather than leaving a blanket exemption or expansion.
|
||||
- Keep offline default tests, required build targets, fresh-version checks,
|
||||
clean candidate/exact source/tag guards, and explicit-ref publication.
|
||||
- Treat ordinary review and roadmap retirement as preparation, not new human
|
||||
approval rounds. Evaluate incidental file prohibitions by their impact on tagged
|
||||
source rather than banning ignored local files solely because they exist.
|
||||
- End at successful tag push, without CI polling, asset-availability gates, or
|
||||
successful-push read-back requirements. Resolve failed/ambiguous pushes from
|
||||
remote evidence and report asynchronous delivery separately.
|
||||
- Align recovery guidance: transient delivery failures alone do not require new
|
||||
versions. Retries/missing-asset additions must preserve published content and
|
||||
checksum consistency; source/content corrections require a new release.
|
||||
|
||||
Apply the formatting convention prospectively. Do not retrofit published tags,
|
||||
release notes, binaries, or checksums. Any actual historical omission discovered
|
||||
during the inventory requires deliberate treatment under the applicable terms
|
||||
and existing release correction policy, not silent rewriting of a release.
|
||||
Expected implementation surfaces include `scripts/check-release-candidate.sh`,
|
||||
`scripts/release.sh`, shared helpers/builders where needed, and release tests.
|
||||
Review workflow references for consistency without expanding into unrelated CI
|
||||
repair or application behavior changes.
|
||||
|
||||
## Scope Boundaries
|
||||
## Boundaries and Completion Evidence
|
||||
|
||||
- No license change, automatic copyright-year advancement, or blanket per-file
|
||||
header requirement.
|
||||
- No mandatory scanner, full SBOM, recurring legal sign-off, new release approval
|
||||
gate, or new network availability requirement.
|
||||
- No automatic requirement for separate downloadable license assets, source
|
||||
bundles, or a different binary packaging format. Concrete obligations found
|
||||
during the inventory still require their applicable treatment.
|
||||
- No changes to application behavior, dependency versions, platform support,
|
||||
or successful-tag-push release completion.
|
||||
- No wholesale replacement of Narratio-specific policy with generic templates.
|
||||
- No adoption in this scope of broader release-process changes to
|
||||
validation, repeated checks, fixed note sections, or release preparation.
|
||||
Those changes warrant a separate deliberate review of policy, scripts, and
|
||||
tests. The licensing additions must not silently enact them.
|
||||
No application relicensing, automatic copyright-year advancement, blanket headers,
|
||||
dependency upgrade, runtime feature, or platform expansion is included. Do not add
|
||||
mandatory scanners, a full SBOM, recurring legal sign-offs, publication-time network
|
||||
checks, or release approval gates. New downloadable license assets or packaging
|
||||
formats are not required merely to implement the conventions; concrete component
|
||||
obligations still require their applicable treatment.
|
||||
|
||||
## Completion Evidence
|
||||
Apply formatting prospectively. Preserve published tags, notes, binaries, and
|
||||
checksums. Address any discovered historical omission deliberately under the
|
||||
applicable terms and correction policy, not by silently rewriting releases.
|
||||
|
||||
The tailored policy and ownership/routing changes are present; the inventory
|
||||
covers the material identified by the source/distribution review; entries have
|
||||
faithful notices and exact source revisions; applicable local texts and companion
|
||||
links are complete; README and release guidance provide the prescribed navigation;
|
||||
and local documentation checks pass. Historical releases and existing publication
|
||||
guards remain unchanged. Review must establish these facts rather than treating
|
||||
the mere existence of new Markdown files as completion.
|
||||
Completion requires comparison with the pinned source, accurate per-file metadata
|
||||
and material attribution, justified variations, substantive supporting documents,
|
||||
valid navigation, and complete applicable texts. Release procedures and tests must
|
||||
prove the selected workflow and guards without duplicate mandatory validation or
|
||||
CI waiting. Documentation checks and relevant release tests must pass. Merely
|
||||
creating Markdown files is not evidence of alignment.
|
||||
|
||||
No product decisions remain open for this scope. Component-specific rights or
|
||||
distribution questions discovered during the inventory must be surfaced with
|
||||
evidence rather than guessed or expanded into blanket restrictions.
|
||||
No product-level decision remains open from the approved review. Concrete rights
|
||||
questions or gate tradeoffs unresolved by the risk-based approach must be surfaced
|
||||
with evidence during planning, not silently converted into stronger requirements.
|
||||
|
||||
Reference in New Issue
Block a user