--- 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//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//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.