Decide the publish destination of a release (ADR-0007)

Task: MIL-004#4

docs/adr/adr-0007-release-publish-destination.md

@@ -0,0 +1,106 @@
+# ADR-0007: Publish destination and token scope of a release
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | ADR-0007 |
+| CrossReference | [MIL-004], [UC-006], [ADR-0006] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version (RC-047) | pending |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+ADR-0006 decides that this repository is released as a whole with a version
+tag and a release page generated from `CHANGELOG.md`. Task 4 of MIL-004 asks
+where a release is published and which permission publishing needs, before the
+release workflow (task 5) is written.
+
+Facts that shape the decision:
+
+- This repository contains workflows, scripts and guides. Nothing is compiled
+  or packaged: a consumer receives a release by referencing the tag
+  (`uses: ...@v1`), not by downloading a file.
+- The Gitea instance (1.27.3) offers, through its REST API, creation of tags
+  and of releases, deletion of a tag, and attachments on a release.
+- The repository is mirrored to GitHub, but the shared workflows are called
+  from Gitea runners of four organizations, so consumers read the Gitea copy.
+- Creating a release and moving the major tag are the two sensitive writes of
+  the release process (ADR-0006).
+
+Options for the destination:
+
+1. **The release page of this repository** (tag plus notes from the changelog).
+2. **A package in the Gitea package registry** (for example a generic package
+   holding an archive of the repository).
+3. **A release page on the GitHub mirror** in addition to option 1.
+4. **Tags only**, without a release page.
+
+Options for the permission:
+
+a. **The token the job receives for its own run**, limited to this repository.
+b. **A dedicated secret** with a personal access token that may write to this
+   repository only.
+c. **The existing `TOKEN_FOR_GITEA`** of the organization.
+
+## Decision
+
+A release is published as the release page of `TirSystem/github-action` on
+Gitea, created from the changelog entry for the tag, with no package and no
+attachments, and the release workflow publishes it with the token its own run
+receives (options 1 and a). If that token proves unable to create the tag or
+to move the major tag, the fallback is a dedicated secret
+`TOKEN_FOR_GITEA_RELEASE` that may write to this repository only (option b).
+`TOKEN_FOR_GITEA` is not used for releases.
+
+The rules that follow from it:
+
+- **What is published:** the tag `vMAJOR.MINOR.PATCH`, the major tag, and one
+  release page whose body is the output of
+  `python tools/changelog.py notes x.y.z`.
+- **Permission needed:** write access to the contents of this repository
+  (create a tag, create and edit a release, delete and recreate the major
+  tag), nothing else. It needs no access to other repositories, to the wiki or
+  to organization settings.
+- **The GitHub mirror** receives the tags through its normal mirroring and has
+  no release page of its own; the changelog file is the same on both.
+- **A package registry is reconsidered** only if a release ever contains a
+  built file that consumers download.
+
+## Consequences
+
+**Positive:**
+
+- One place, the release page, shows what changed and whether to act, next to
+  the tag consumers pin.
+- No new secret is stored while the job token is enough, and the permission is
+  limited to one repository and the lifetime of one run.
+- Nothing to build, sign or version besides the tag.
+
+**Negative:**
+
+- The job token may not be allowed to move a tag where tag protection is set;
+  this is not verified until the release workflow of task 5 runs, and the
+  fallback needs a secret that someone must create and rotate.
+- Consumers on GitHub see tags but no release page.
+- Without attachments a consumer cannot download a release as a file; the tag
+  is the only form.
+
+## Affected Artifacts
+
+- [MIL-004] — decides criterion 4 of its Go/No-Go table and unlocks task 5.
+- [UC-006] — "the release page for the tag is created from the changelog
+  entry" states where.
+- [ADR-0006] — whose release steps this publishes.
+
+---
+
+[MIL-004]: ../milestones/mil-004-versioned-release.md
+[UC-006]: ../uc-006/uc.md
+[ADR-0006]: ./adr-0006-release-process-and-version-pinning.md

docs/artifact-registry.md

@@ -11,9 +11,9 @@ each document lives in *this* project and the next version to use.
 | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
 | PP | Project Plan | docs/project-plan.md | 002 |
 | MIL | Milestone / Gateway | docs/milestones/*.md | 007 |
-| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 047 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 048 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
-| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0007 |
+| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0008 |
 | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
 | US | User Story | docs/user-stories.md | 002 |
 | UC | Use Case | docs/uc-NNN/uc.md | 008 |

docs/sqa/reviews/rc-047-adr-0007.md

@@ -0,0 +1,50 @@
+# Review Record: ADR-0007
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-047 |
+| CrossReference | [ADR-0007], [QC-ADR-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [ADR-0007]
+- Checklist used: [QC-ADR-001]
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | ADR-0007 in `adr-0007-release-publish-destination.md`, after ADR-0006. |
+| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | States what the repository contains, what the API offers and the two sensitive writes. |
+| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Four options for the destination and three for the permission. |
+| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | Options 1 and a, with a named fallback b; the fallback is conditional on a fact the ADR says is unverified. |
+| 5 | Consequences list both Positive and Negative outcomes | Pass | Three positive and three negative. |
+| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Security (permission scope and secret) and portability (no release page on GitHub) are named. |
+| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | MIL-004, UC-006 and ADR-0006 are linked and cited. |
+| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | Initial row only. |
+| 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | Nothing is superseded. |
+| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | No abbreviation without expansion. |
+| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Accepted. |
+
+## Overall Verdict
+
+Go - all applicable criteria pass. The behaviour of the job token is an assumption that the first run of the release workflow (task 5) verifies, with the fallback already named. S01 gave the Go in chat on 2026-10-10, standing in for the other reviewers as ADR-0002 records; there is no independent reader.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Verify in the first run of the release workflow that the job token creates the tag and moves the major tag; if not, create `TOKEN_FOR_GITEA_RELEASE` | S05 | 2026-11-28 |
+
+---
+
+[ADR-0007]: ../../adr/adr-0007-release-publish-destination.md
+[QC-ADR-001]: ../../../framework/qc/qc-adr.md

docs/sqa/traceability-matrix.md

@@ -4,13 +4,13 @@
 | Key | Value |
 | --- | --- |
 | ID | TM-001 |
-| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [RC-018], [RC-019], [RC-020], [RC-021], [RC-022], [RC-023], [RC-024], [RC-025], [RC-026], [RC-027], [RC-028], [RC-029], [RC-030], [RC-031], [RC-032], [RC-033], [RC-034], [RC-035], [RC-036], [RC-037], [RC-038], [RC-039], [RC-040], [RC-041], [RC-042], [RC-043], [RC-044], [RC-045], [RC-046], [UC-007], [UC-006], [ADR-0006], [UC-005], [ADR-0005], [UCD-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] |
+| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [RC-018], [RC-019], [RC-020], [RC-021], [RC-022], [RC-023], [RC-024], [RC-025], [RC-026], [RC-027], [RC-028], [RC-029], [RC-030], [RC-031], [RC-032], [RC-033], [RC-034], [RC-035], [RC-036], [RC-037], [RC-038], [RC-039], [RC-040], [RC-041], [RC-042], [RC-043], [RC-044], [RC-045], [RC-046], [RC-047], [ADR-0007], [UC-007], [UC-006], [ADR-0006], [UC-005], [ADR-0005], [UCD-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] |
 
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added UC-006, ADR-0006 and RC-040 to RC-043 | [044d8ba] |
+| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added UC-007 and RC-044 to RC-046 | [4cf52af] |
-| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added UC-007 and RC-044 to RC-046 | [4cf52af] |
+| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added ADR-0007 and RC-047 | pending |
 
 ---
 
@@ -65,6 +65,7 @@ updated whenever an artifact instance is created or reviewed.
 | [ADR-0005] | ADR | [MIL-003], [UC-005], [US-001], [ADR-0004] | - | [RC-038] |
 | [UC-006] | UC | [UCD-001], [US-001], [SA-001] | [ADR-0006] | [RC-042] |
 | [ADR-0006] | ADR | [MIL-004], [UC-006], [US-001], [ADR-0004], [ADR-0005] | - | [RC-043] |
+| [ADR-0007] | ADR | [MIL-004], [UC-006], [ADR-0006] | - | [RC-047] |
 | [UC-007] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-044] |
 | [RC-019] | RC | [UCD-001] | - | - |
 | [RC-020] | RC | [US-001] | - | - |
@@ -94,6 +95,7 @@ updated whenever an artifact instance is created or reviewed.
 | [RC-044] | RC | [UC-007] | - | - |
 | [RC-045] | RC | [UCD-001] | - | - |
 | [RC-046] | RC | [US-001] | - | - |
+| [RC-047] | RC | [ADR-0007] | - | - |
 
 ## Coverage Notes
 
@@ -169,10 +171,11 @@ updated whenever an artifact instance is created or reviewed.
 [RC-044]: ./reviews/rc-044-uc-007.md
 [RC-045]: ./reviews/rc-045-ucd-001-consume.md
 [RC-046]: ./reviews/rc-046-us-001-consume.md
+[RC-047]: ./reviews/rc-047-adr-0007.md
+[ADR-0007]: ../adr/adr-0007-release-publish-destination.md
 [UC-007]: ../uc-007/uc.md
 [UC-006]: ../uc-006/uc.md
 [ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
 [UC-005]: ../uc-005/uc.md
 [ADR-0005]: ../adr/adr-0005-quality-check-contract.md
-[044d8ba]: https://git.tirsystem.com/TirSystem/github-action/commit/044d8ba21f96f4aceb807d62addc35cdcbb56051
 [4cf52af]: https://git.tirsystem.com/TirSystem/github-action/commit/4cf52afe00f546c6b20424fb8dfc12796ffd9296

guides/release-process.md

@@ -43,6 +43,8 @@ Until the release workflow exists (MIL-004 task 5) the steps are done by hand.
    ```
 6. **Announce.** Create the release page for the tag with the text of
    `python tools/changelog.py notes x.y.z`, and say whether consumers must act.
+   The release page of this repository on Gitea is the only destination
+   (ADR-0007); nothing is attached to it.
 7. **Verify.** One repository pinned to the previous exact tag still runs the
    same code; one repository on the major tag receives the release.