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
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.
139 lines
5.7 KiB
Markdown
139 lines
5.7 KiB
Markdown
---
|
||
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.
|