From f060d7eb1fbf51da4ed334f997745a0cb06487e3 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 26 Sep 2026 20:45:59 +0000 Subject: [PATCH] Document licensing policy alignment roadmap --- docs/roadmap/policy.md | 187 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 docs/roadmap/policy.md diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md new file mode 100644 index 0000000..43559b9 --- /dev/null +++ b/docs/roadmap/policy.md @@ -0,0 +1,187 @@ +# Align Licensing Documentation With the Standard Policy + +Status: Accepted; implementation pending. + +## Goal + +Adopt the upstream 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. + +This roadmap defines the target and scope, not implementation sequencing. + +## Current Baseline + +The standard policy checkout at `../policy`, reviewed on 2026-09-26, provides +OSS policy v1.2 and licensing additions in documentation policy v1.5 and release +policy v1.2. Its standard license reference collection supplies reusable texts; +it is not a bundle that every consumer must copy in full. + +Narratio currently has: + +- 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 upstream GPLv3 reference 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 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. + +## Targeted End State + +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. + +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. + +## Required Changes + +### Adopt a Tailored OSS Policy + +Add `docs/policy/oss.md` from upstream v1.2, retaining its actual 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. + +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. + +Retain upstream's 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. + +### Establish Canonical Ownership and Contributor Routing + +Incorporate the licensing-related additions from upstream documentation policy +v1.5 into `docs/policy/documentation.md`, preserving Narratio-specific ownership +and existing unrelated decisions. Clearly assign: + +- 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`. + +Record the selective upstream adoption accurately; do not imply the entire +upstream policy set has 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. + +### Establish the Attribution Inventory + +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 upstream 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. + +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. + +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. + +### Add README and Release Navigation + +End README with two friendly statements linking to the existing GPL v3-or-later +grant in COPYRIGHT and the new attribution document. + +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. + +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. + +### Keep Ongoing Maintenance Proportionate + +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. + +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. + +## Scope Boundaries + +- 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 upstream release v1.2's broader 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 + +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. + +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.