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.
|
Status: Accepted; implementation pending.
|
||||||
|
|
||||||
## Goal
|
## Goal and Approved Scope
|
||||||
|
|
||||||
Adopt the agreed licensing-documentation conventions without changing
|
Align Narratio's adopted policy language with Standard Repository Policies.
|
||||||
Narratio's license, runtime behavior, or release responsibility boundary. Make
|
Use upstream wording verbatim for non-substantive differences. Retain variations
|
||||||
project licensing and upstream attribution easy to find and maintain through
|
only for substantive, locally significant requirements or decisions and explain
|
||||||
ordinary development and release preparation.
|
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,
|
The approved review compared current local documents directly with upstream
|
||||||
and README/release navigation. Policy templates are internal administrative
|
commit `d84a38ebab26f048cafbe59a2246700c35d29843`, verified against published
|
||||||
material, not an attribution source. Do not cite or link their repository,
|
`main` on 2026-09-28. Historical adoption baselines need not be reconstructed.
|
||||||
filesystem location, or contents in Narratio documentation. Adopted policies
|
Do not imply that this revision was previously adopted.
|
||||||
must be self-contained; license texts and component notices must trace to their
|
|
||||||
actual public publishers and upstream projects.
|
|
||||||
|
|
||||||
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
|
Narratio has five adopted policies without per-document Upstream Source links.
|
||||||
`GPL-3.0-or-later` grant, warranty disclaimer, and third-party-material caveat.
|
It lacks `docs/policy/meta.md`, `docs/policy/oss.md`, and the OSS attribution
|
||||||
- A complete root `LICENSE` matching the standard GPLv3 text except
|
collection. Its development guide has task routes but not the standard selective
|
||||||
for a missing final newline. No substantive licensing correction is needed.
|
policy-reading guidance. COPYRIGHT already grants GPL-3.0-or-later and LICENSE
|
||||||
- Documentation policy based on v1.1, without the new licensing ownership map,
|
contains GPLv3; only the separate policy-document licensing scope needs adding.
|
||||||
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 publishes source and tagged Linux amd64/arm64 and best-effort macOS
|
The release process already ends at successful tag publication to `origin`, uses
|
||||||
arm64 binaries with checksums. Successful publication of the intended tag to
|
lightweight tags and source-push-before-tag, and publishes Gitea binaries and
|
||||||
`origin` remains the release command's responsibility boundary; asset publication
|
checksums asynchronously. Current guidance requires standalone validation before
|
||||||
is asynchronous. The current dependency graph includes ConfigKit, AWS modules,
|
publication repeats it. The checker requires fixed note sections and repeats
|
||||||
Go extension packages, YAML libraries, and test dependencies. This roadmap does
|
documentation/example tests included in the full suite. These are alignment
|
||||||
not claim that their individual terms or attribution coverage have been audited.
|
work, not automatic justifications for different policy language.
|
||||||
|
|
||||||
ConfigKit is now selected at v0.4.1, whose patch contains licensing/documentation
|
## Policy Target
|
||||||
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.
|
|
||||||
|
|
||||||
## 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
|
No existing policy is wholly unchanged because provenance and wording require
|
||||||
licensing documentation, and a canonical attribution inventory accurately
|
updates. Narratio's architectural decisions and agent commit behavior need no
|
||||||
describes material incorporated into or distributed with Narratio. Applicable
|
substantive change. Wording preferences alone do not justify local variants.
|
||||||
standard texts are available locally; project-specific upstream notices and
|
|
||||||
source links identify the actual imported commits.
|
|
||||||
|
|
||||||
README and future release documents navigate to these canonical materials.
|
## Provenance and Orientation
|
||||||
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.
|
|
||||||
|
|
||||||
## 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
|
Substitute the correct filename for each policy. Preserve accurate provenance in
|
||||||
and recording the adoption date. Remove template instructions and adapt links
|
later edits; Git records suffice without a new adoption registry or sync service.
|
||||||
that point to template-only examples or reference collections. Do not introduce
|
|
||||||
placeholder documents merely to satisfy those links.
|
|
||||||
|
|
||||||
Identify Narratio's existing application license and connect the policy to the
|
Adapt upstream `agents/AGENTS.md` into root `AGENTS.md`, preserving applicable
|
||||||
canonical repository and release documentation for its Gitea host, distribution
|
existing instructions. Do not copy upstream's root agent instructions, which
|
||||||
channels, and publication mechanism. Preserve the author's license choice;
|
govern work on that repository. Incorporate the supplied selective Policy Reading
|
||||||
adoption is not relicensing. Leave COPYRIGHT and LICENSE substantively intact;
|
Guide into `docs/development.md`: select by task, read before governed decisions,
|
||||||
normalizing the final newline is optional formatting only.
|
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:
|
Meta links to the [public project](https://gitea.maximumdirect.net/eric/policy)
|
||||||
project-specific license and attribution material is linked at its imported
|
and [current adoption guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
|
||||||
commit rather than copied locally solely because its terms use reproduction,
|
These are current-discovery links; adopted-source and example links stay
|
||||||
inclusion, or copy language. This convention does not establish license
|
commit-pinned. Reading triggers belong in development guidance and formal credit
|
||||||
compatibility or discharge distinct obligations such as modified-file notices
|
in attribution, not duplicated in meta.
|
||||||
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.
|
|
||||||
|
|
||||||
### Establish Canonical Ownership and Contributor Routing
|
## Justified Local Customizations
|
||||||
|
|
||||||
Incorporate the agreed licensing ownership additions into
|
Preserve established stage/adapter boundaries, manifest-driven resume/restore,
|
||||||
`docs/policy/documentation.md`, preserving Narratio-specific ownership
|
artifact/path contracts, publication and lock semantics, credential protections,
|
||||||
and existing unrelated decisions. Clearly assign:
|
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`.
|
Retain Linux amd64/arm64 and best-effort macOS arm64 deliverables, without new
|
||||||
- Complete project license text to `LICENSE`.
|
native-platform gates or Windows/Intel Mac support. Preserve `origin/main`,
|
||||||
- General licensing and attribution conventions to `docs/policy/oss.md`.
|
lightweight tags, and source-push-before-tag in the release procedure. These are
|
||||||
- Component-specific attribution to `docs/oss/attribution.md`.
|
permitted project-specific mechanics, not exceptions to tag-push completion.
|
||||||
- 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`.
|
|
||||||
|
|
||||||
Record the selective policy update accurately; do not imply unrelated policy
|
Customize documentation ownership for real Narratio interfaces and responsibilities,
|
||||||
changes have been adopted by merely changing version metadata.
|
including troubleshooting; do not create empty API/consumer documents. Keep common
|
||||||
Add a task-specific reading route in `docs/development.md` for licensing,
|
prose verbatim around these customizations and explain substantive local choices
|
||||||
dependency, attribution, and release-document changes. Avoid repeating the OSS
|
in their canonical owner rather than maintaining a parallel general policy essay.
|
||||||
rules in the agent, architecture, or testing policies.
|
|
||||||
|
|
||||||
### Establish the Attribution Inventory
|
## Licensing, Attribution, and Local Materials
|
||||||
|
|
||||||
Review actual incorporated and distributed material, including relevant
|
Create `docs/oss/attribution.md` with the prescribed title followed directly by
|
||||||
transitive dependencies, Go runtime material in binaries, and copied code or
|
factual component entries. Use the canonical Standard Repository Policies entry
|
||||||
assets. Use the selected source revisions and actual use/distribution to decide
|
from the reviewed commit. Identify actual copied/adapted material, including policy
|
||||||
coverage, not just direct entries in `go.mod`. Neither every development tool
|
files, adapted agent instructions, and copied reading-guide material as applicable.
|
||||||
nor every separately installed subprocess application automatically belongs in
|
Preserve creator, copyright, license, disclaimer, and modification notices. Pin
|
||||||
the inventory. Review any such component if Narratio actually incorporates or
|
source, COPYRIGHT, and LICENSE links to the reviewed full commit.
|
||||||
distributes it.
|
|
||||||
|
|
||||||
Create `docs/oss/attribution.md` with the agreed five-field format: project
|
Copy CC-BY-SA-4.0 into `docs/oss/licenses/`. Add the limited policy-document scope
|
||||||
name, faithful upstream copyright statements, applicable SPDX expression,
|
to COPYRIGHT with an attribution link: adapted policy material remains CC-BY-SA-4.0;
|
||||||
license/notice links, and a source repository link. Preserve multiple statements,
|
Narratio's application code remains GPL-3.0-or-later. Root LICENSE needs no
|
||||||
licensing alternatives, versions, and exceptions where applicable. Do not infer
|
replacement. Original upstream licensing-example formatting is CC0 and alone
|
||||||
ownership or invent identifiers; identify nonstandard terms through their texts.
|
does not require attribution.
|
||||||
|
|
||||||
Resolve source and notice links to the exact imported commit, including for
|
Complete the previously agreed inventory of incorporated/distributed material:
|
||||||
copied material. Version tags and moving branches are not substitutes for those
|
relevant transitive dependencies, Go runtime material in shipped binaries, and
|
||||||
component commit links. Inspect the selected source's license and notices rather
|
copied code, documentation, or assets. Inspect selected sources and actual use;
|
||||||
than assuming terms from a dependency name or current upstream main branch.
|
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
|
Follow OSS v1.8's ordered fields and presentation: project heading, applicable
|
||||||
`docs/oss/licenses/`. Reuse a text across entries where appropriate, but preserve
|
faithful copyright statements, applicable SPDX expression, license/notice links,
|
||||||
distinct versions and exceptions. Make required companion texts directly
|
and a link labeled `Source` to the exact commit, ending with a period.
|
||||||
reachable from the affected entry; LGPLv3, if applicable, includes GPLv3.
|
Optional identification remains factual. Preserve
|
||||||
Classify upstream files by content, not filename: a LICENSE file containing
|
alternatives, exceptions, and required notices; do not invent identifiers or add
|
||||||
project-specific notices may require both its upstream link and a local standard
|
research narratives, compliance conclusions, or exception reasoning to entries.
|
||||||
text link. Keep explanatory prose outside the verbatim texts.
|
|
||||||
|
|
||||||
### 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
|
Keep upstream's README, root AGENTS.md, development/adoption guides, and example
|
||||||
grant in COPYRIGHT and the new attribution document.
|
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
|
End README with the prescribed grant and attribution links. Future release notes
|
||||||
`docs/release.md` to give the concrete Narratio Gitea URL construction. Each new
|
and hosted pages end with `COPYRIGHT | LICENSE | ATTRIBUTION` links at their
|
||||||
release document and its hosted download page must end with three links whose
|
immutable release tag or source revision. The procedure owns concrete Gitea URLs;
|
||||||
visible text is `COPYRIGHT | LICENSE | ATTRIBUTION`. Use absolute URLs at that
|
continue using the checked-in note as the hosted body. Maintain attribution with
|
||||||
release's immutable tag or corresponding immutable source revision. Unlike
|
relevant dependency/material changes through ordinary review.
|
||||||
upstream component links, these release-navigation links may use the release tag.
|
|
||||||
|
|
||||||
Retain reuse of the checked-in release note by `.woodpecker/release.yml`; no new
|
## Coordinated Release Alignment
|
||||||
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.
|
|
||||||
|
|
||||||
### 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
|
- Make publication the normal validating-and-publishing entry point. Standalone
|
||||||
add, remove, upgrade, copy, or alter distribution of relevant components. Review
|
validation remains optional rather than a mandatory duplicate prior pass.
|
||||||
faithful license text copies, statements, and destinations through ordinary
|
- Remove fixed release-note section requirements. Preserve version-matched notes
|
||||||
change review and existing local documentation checks.
|
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,
|
Expected implementation surfaces include `scripts/check-release-candidate.sh`,
|
||||||
release notes, binaries, or checksums. Any actual historical omission discovered
|
`scripts/release.sh`, shared helpers/builders where needed, and release tests.
|
||||||
during the inventory requires deliberate treatment under the applicable terms
|
Review workflow references for consistency without expanding into unrelated CI
|
||||||
and existing release correction policy, not silent rewriting of a release.
|
repair or application behavior changes.
|
||||||
|
|
||||||
## Scope Boundaries
|
## Boundaries and Completion Evidence
|
||||||
|
|
||||||
- No license change, automatic copyright-year advancement, or blanket per-file
|
No application relicensing, automatic copyright-year advancement, blanket headers,
|
||||||
header requirement.
|
dependency upgrade, runtime feature, or platform expansion is included. Do not add
|
||||||
- No mandatory scanner, full SBOM, recurring legal sign-off, new release approval
|
mandatory scanners, a full SBOM, recurring legal sign-offs, publication-time network
|
||||||
gate, or new network availability requirement.
|
checks, or release approval gates. New downloadable license assets or packaging
|
||||||
- No automatic requirement for separate downloadable license assets, source
|
formats are not required merely to implement the conventions; concrete component
|
||||||
bundles, or a different binary packaging format. Concrete obligations found
|
obligations still require their applicable treatment.
|
||||||
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.
|
|
||||||
|
|
||||||
## 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
|
Completion requires comparison with the pinned source, accurate per-file metadata
|
||||||
covers the material identified by the source/distribution review; entries have
|
and material attribution, justified variations, substantive supporting documents,
|
||||||
faithful notices and exact source revisions; applicable local texts and companion
|
valid navigation, and complete applicable texts. Release procedures and tests must
|
||||||
links are complete; README and release guidance provide the prescribed navigation;
|
prove the selected workflow and guards without duplicate mandatory validation or
|
||||||
and local documentation checks pass. Historical releases and existing publication
|
CI waiting. Documentation checks and relevant release tests must pass. Merely
|
||||||
guards remain unchanged. Review must establish these facts rather than treating
|
creating Markdown files is not evidence of alignment.
|
||||||
the mere existence of new Markdown files as completion.
|
|
||||||
|
|
||||||
No product decisions remain open for this scope. Component-specific rights or
|
No product-level decision remains open from the approved review. Concrete rights
|
||||||
distribution questions discovered during the inventory must be surfaced with
|
questions or gate tradeoffs unresolved by the risk-based approach must be surfaced
|
||||||
evidence rather than guessed or expanded into blanket restrictions.
|
with evidence during planning, not silently converted into stronger requirements.
|
||||||
|
|||||||
Reference in New Issue
Block a user