Files
CV_Site_Nuxt/OKF_Nuxt/decisions/release-engineering.md
T
Noel Sabia a2259df877
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / Lint + typecheck (pull_request) Successful in 1m10s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 6s
PR Check / Dependency audit (pull_request) Successful in 9s
PR Check / Dockerfile lint (droast) (pull_request) Successful in 6s
PR Check / AI code review (opencode) (pull_request) Successful in 22s
fix(ci): point changelog compare links at our Gitea
The generated CHANGELOG linked every release to
github.com/CV_Website/CV_Site_Nuxt, a host this repository does not live
on. release-please takes the compare host from the configuration, so it
is set now.

The decision record also gains the real reason no tag was ever created:
Gitea rewrites a merged PR's head.ref to refs/pull/<n>/head once the head
branch is deleted, and the Gitea build parses that field as the release
branch. BranchName.parse then fails and the release is dropped with a
logged error while the run still exits 0. The repository deleted every
merged branch; that default is off now, and the versions the manifest
already consumed have to be tagged by hand.
2026-10-27 12:20:28 +01:00

139 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
type: Decision
title: Release engineering
description: Releases are produced by release-please in manifest mode, driven by conventional commits, with the message format enforced at commit time by commitizen.
tags: [decision, release, release-please, ci]
status: draft
generated: { by: opencode-go/glm-5.3-flash, at: 2026-10-18T16:05:00Z }
verified: { by: human:noel, at: not yet }
sources:
- id: config
resource: release-please-config.json
title: release-please configuration
- id: manifest
resource: .release-please-manifest.json
title: release-please manifest
- id: workflow
resource: .gitea/workflows/release-please.yml
title: release-please workflow
---
# Decision
On every push to `main`, release-please (manifest mode) collects
conventional commits, derives the next version, and opens a release PR
that bumps `package.json`, updates `CHANGELOG.md` and moves the manifest
forward. Merging that PR creates the release. The message format that
feeds this machine is enforced locally by the commitizen pre-commit hook.
# Why
* **Manifest mode** (config JSON + manifest JSON) over inline
`release-type` in the workflow: the configuration becomes part of the
repository, reviewable in PRs, instead of buried in workflow YAML.
* **Plain tags** (`v1.0.0`, `include-component-in-tag: false`):
single-package repository; component-prefixed tags would be noise.
* **A `version` field in `package.json`**: the `node` release type reads
it; without the field the release machinery cannot track anything.
* **Enforcement at commit time**: a non-conventional message is not an
error release-please reports — it just silently produces no release.
Commitizen turns that silent failure into a blocked commit.
# How a release happens, end to end
1. Work lands on branches as conventional commits (`feat:`, `fix:`,
`chore:`, …), enforced by the local hook.
2. Merge to `main` → release-please opens/updates a release PR
(`chore(main): release …`).
3. Merge the release PR → version bumped, changelog written, tag
`vX.Y.Z` created.
# The label is load-bearing (2026-10-24)
Steps 2 and 3 are connected by a label, not by the merge alone:
* release-please creates the release PR with `autorelease: pending`;
* on the next run it lists merged PRs and keeps only those carrying that
label; those are the releases it tags.
Gitea resolves label **names** in `POST /issues/{index}/labels` with
`GetLabelIDsInRepoByNames`, which is a SQL `IN` filter: names that do not
exist are dropped **without an error**. A repository with no labels
therefore accepts the call, returns 200, and attaches nothing.
That is exactly what happened here: PRs #20 and #21 were merged as release
PRs with no label at all, so every run found zero merged release PRs,
created zero tags, and opened the next release PR instead — while reporting
success. Three release PRs, no tags.
The workflow now creates both labels (`autorelease: pending`,
`autorelease: tagged`) before the action runs. Idempotent: it reads the
label list and creates only what is missing.
# The head branch must survive the merge (2026-10-27)
The label fix was necessary but not sufficient. PR #22 carried
`autorelease: pending` when it was merged, and the run after it still
created no tag. From its log (task 475):
```
❯ Found pull request #22: 'chore: release main'
✖ Bad branch name: refs/pull/22/head
⚠ Expected 1 releases, only found 0
```
Gitea rewrites a merged PR's `head.ref` to `refs/pull/<n>/head` once the
head branch is deleted; the branch name survives only in `head.label`.
The Gitea build of release-please reads `head.ref`
(`BranchName.parse(mergedPullRequest.headBranchName)`, bundled at
`dist/index.js:15288`) and abandons the release when it is not a release
branch. GitHub keeps the branch name there, which is why the plugin's
assumption holds on GitHub and not here.
The repository deleted the head branch of every merged PR
(`default_delete_branch_after_merge: true`). It is `false` now, and a
release PR must be merged with its branch kept. The mechanism was
confirmed by comparison, not inference: while `fix/release_please` still
existed, PR #23 reported `head.ref = fix/release_please`; every PR whose
branch was gone reported `refs/pull/<n>/head`.
# Recovering the versions that never got a tag
The label alone cannot recover them — #20, #21 and #22 all lost their head
branch, so release-please skips them for the reason above. Creating those
tags is a one-time manual step:
| Version | Merge commit |
|---|---|
| `v1.1.0` | `67cf232` (#12) |
| `v1.2.0` | `4e8aa28` (#20) |
| `v1.3.0` | `08eb042` (#21) |
| `v1.4.0` | `0c937e6` (#22) |
`v1.0.0` is the bootstrap changelog entry from the configuration commit
`c89747e` (2026-10-18); no release PR produced it.
The manifest moved to 1.4.0 without any tag existing, so until a tag is
present release-please has no baseline: it reported "No latest release
found for path: ., component: , but a previous version (1.4.0) was
specified in the manifest" and would compute the next release from the
whole history.
# Not verified
* That the release phase tags correctly once the head branch survives a
merge. The next release cycle proves it.
* That `RELEASE_PLEASE_TOKEN_CV_SITE_NUXT` carries the `write:issue`
scope the same way `PR_GITEA_TOKEN` needed it; the previous failure
was an immediate API rejection consistent with a scope problem.
# Revisit when
* A second package appears in the repository (then
`include-component-in-tag` and `separate-pull-requests` matter).
* A release must trigger a deploy — the workflow gains a step after
`release_created` is set.
* The label step breaks: if Gitea ever starts rejecting unknown label
names, the `Ensure release-please labels exist` step will fail loudly
instead of silently, which is the point.