docs(tags): document tag creation behavior explicitly — Forgejo release API vs git push --tags #359

New issue

Closed

opened 2026-07-03 23:42:49 +02:00 by bosun · 1 comment

bosun commented

2026-07-03 23:42:49 +02:00

Owner

Empirical finding (external cold-read round 2)

External reviewer: "I did not see a normal git tag && git push --tags release path. draft-release.sh appears to rely on the Forgejo release API creating or binding the tag via tag_name / target_commitish. That needs proof."

Reviewer verbatim: "A release automation tool should make tag creation painfully obvious. Here it seems delegated to Forgejo release creation. That may work, but I want proof, especially across Forgejo/Codeberg/Gitea variants."

Blocking rationale

Tag creation is central to a release tool's value. Adopters need to know: what creates the tag, when, at what commit, and what happens if the tag exists already or points elsewhere.

Fix path

Add explicit Tag Creation section to docs/integration.md
Name the mechanism: Forgejo release API creates the tag via tag_name + target_commitish fields
Name the anchor: what commit does the tag point to (the release-prep PR merge commit, or the manifest-bump commit)
Name behavior when tag already exists (idempotency check in draft-release.sh)
Name behavior when tag exists but points elsewhere (fail loud, don't silently update)
Cross-Forgejo-variant testing status (Forgejo verified; Gitea untested; Codeberg via mirror — the mirror workflow #309 confirms Codeberg tag creation)

Verification AC

Adopter reads the section and knows exactly what tag will be created + where it will point + how re-runs behave
External cold-read round 3 finds no tag-creation-behavior ambiguity

Anchor

External outside-model cold-read round 2 (fresh ChatGPT session, 2026-07-03 late) returned new findings after Pilot Cold-Read delta had cleared. External verdict: 'promising but not yet trustworthy.' Operator ratified delta plan 2026-07-03 23:35. This tracker addresses one of the round-2 findings. Success criterion: subsequent external cold-read returns no further objections of this class.

## Empirical finding (external cold-read round 2) External reviewer: "I did not see a normal `git tag && git push --tags` release path. `draft-release.sh` appears to rely on the Forgejo release API creating or binding the tag via `tag_name` / `target_commitish`. That needs proof." Reviewer verbatim: "A release automation tool should make tag creation painfully obvious. Here it seems delegated to Forgejo release creation. That may work, but I want proof, especially across Forgejo/Codeberg/Gitea variants." ## Blocking rationale Tag creation is central to a release tool's value. Adopters need to know: what creates the tag, when, at what commit, and what happens if the tag exists already or points elsewhere. ## Fix path - Add explicit Tag Creation section to docs/integration.md - Name the mechanism: Forgejo release API creates the tag via `tag_name` + `target_commitish` fields - Name the anchor: what commit does the tag point to (the release-prep PR merge commit, or the manifest-bump commit) - Name behavior when tag already exists (idempotency check in draft-release.sh) - Name behavior when tag exists but points elsewhere (fail loud, don't silently update) - Cross-Forgejo-variant testing status (Forgejo verified; Gitea untested; Codeberg via mirror — the mirror workflow #309 confirms Codeberg tag creation) ## Verification AC - Adopter reads the section and knows exactly what tag will be created + where it will point + how re-runs behave - External cold-read round 3 finds no tag-creation-behavior ambiguity ## Anchor External outside-model cold-read round 2 (fresh ChatGPT session, 2026-07-03 late) returned new findings after Pilot Cold-Read delta had cleared. External verdict: 'promising but not yet trustworthy.' Operator ratified delta plan 2026-07-03 23:35. This tracker addresses one of the round-2 findings. Success criterion: subsequent external cold-read returns no further objections of this class.

bosun added the

priority/high

size/S

kind/docs

labels

2026-07-03 23:42:49 +02:00

quartermaster referenced this issue from a commit

2026-07-04 00:03:00 +02:00

docs(tags): explicit tag creation mechanism + idempotency + variants (#359)

quartermaster referenced this issue

2026-07-04 00:03:29 +02:00

docs: round-2 adopter-honesty bundle — tokens + Codeberg positioning + tag creation (#356 #358 #359) #364

quartermaster referenced this issue from a commit

2026-07-04 00:10:32 +02:00

docs(tags): explicit tag creation mechanism + idempotency + variants (#359)

release-bot referenced this issue

2026-07-04 00:10:59 +02:00

chore(release): v0.26.0 #327

quartermaster commented

2026-07-04 00:15:13 +02:00

Owner

Delta merged via PR #364 at 886abbb. Explicit Tag Creation section added to docs/integration.md naming: (1) Forgejo release API creates the tag via tag_name + target_commitish; (2) 4-step sequence at cut time; (3) tag points at rolling-PR merge commit; (4) idempotency behavior for same-tag-same-commit / same-tag-different-commit / same-tag-Forgejo-only; (5) NO git push --tags (bypasses release-object binding + trips ADR-0003). Cross-variant status per Forgejo/Codeberg/Gitea.

Delta merged via [PR #364](https://git.frankenbit.de/frankenbit/release-toolkit/pulls/364) at 886abbb. Explicit Tag Creation section added to `docs/integration.md` naming: (1) Forgejo release API creates the tag via `tag_name` + `target_commitish`; (2) 4-step sequence at cut time; (3) tag points at rolling-PR merge commit; (4) idempotency behavior for same-tag-same-commit / same-tag-different-commit / same-tag-Forgejo-only; (5) NO `git push --tags` (bypasses release-object binding + trips ADR-0003). Cross-variant status per Forgejo/Codeberg/Gitea.

quartermaster closed this issue

2026-07-04 00:15:14 +02:00

bosun referenced this issue

2026-07-04 08:53:27 +02:00

design(v2.0.0): consider Go rewrite for cross-runner + single-binary distribution + refactor-safety #367