--- 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. # Recovering a release that was merged without a label Labels exist only from the fixed workflow onwards. PRs merged before that still carry none, so tagging them is a one-time manual step: ```sh # add the pending label to the merged release PRs for n in 20 21; do curl -sS -X POST -H "Authorization: token $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"labels":["autorelease: pending"]}' \ "https://git.noelsabia.dev/api/v1/repos/CV_Website/CV_Site_Nuxt/issues/$n/labels" done ``` Then run the release-please workflow again (it now has `workflow_dispatch`). It creates `v1.2.0` and `v1.3.0` from those PRs' bodies and replaces the label with `autorelease: tagged`. # Not verified * 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. * That the release phase tags correctly once the label is present. The label path is now fixed at the source; the first recovery run proves it. # 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.