Release and Versioning

Release and Versioning

Timonel uses a trunk-based release model with main as the permanent source branch.

Branch model

short-lived branch -> pull request -> main

There is no permanent development branch in the intended release flow.

Dependabot also targets main.

CI

.github/workflows/ci.yml runs on pull requests and pushes to main.

The CI matrix validates:

Node 22.22.2
Node 24.15.0
Node 26

Node 24 is the coverage job. CI also runs security/quality checks and builds an npm package artifact.

Publishing is intentionally separate from CI.

Canary publication

.github/workflows/publish.yml listens for the completion of the CI workflow.

A canary is eligible only when all of these are true:

• event is workflow_run;
• CI concluded successfully;
• the CI run came from a push;
• the tested branch is main.

The publish job checks out the exact workflow_run.head_sha, so it cannot silently publish a different commit than the one CI tested.

Canary versions follow this shape:

<base>-canary.<release-run-number>.sha<short-sha>

Example from the first successfully validated OIDC flow:

3.1.1-canary.40.sha06b289446863

The npm dist-tag is:

canary

Stable publication

Stable release is a manual workflow_dispatch of publish.yml from main.

The workflow first runs a stable verification job, including CI checks, unit tests, integration tests, and the security audit.

The publish job then enters the protected GitHub environment:

npm-prd

That environment is the approval boundary for stable npm publication.

npm authentication

npm publication uses Trusted Publishing/OIDC rather than a long-lived npm token.

The package has separate npm Trusted Publisher entries for the same GitHub workflow:

KenkoGeek/timonel + publish.yml + npm-canary
KenkoGeek/timonel + publish.yml + npm-prd

Both allow direct npm publish.

The workflow requests:

permissions:
  id-token: write

Do not rename publish.yml casually. npm Trusted Publisher identity includes the workflow filename. A previous rename to release.yml broke publication even though the workflow content itself was valid.

setup-node and OIDC

Publishing jobs intentionally do not set registry-url in actions/setup-node. In this repository, that configuration generated a token-based .npmrc entry using an undefined NODE_AUTH_TOKEN, which prevented the desired Trusted Publishing path.

Keep the explanatory comment in publish.yml unless the npm/setup-node authentication behavior is revalidated end to end.

Provenance

Canary publishing uses:

npm publish --tag canary --provenance

Stable publication sets npm provenance for semantic-release as well.

A successful canary should therefore have npm provenance associated with its GitHub Actions build.

Stable version calculation

Stable releases use semantic-release with only main configured as a release branch.

Typical Conventional Commit effects are:

Commit	Stable SemVer effect
fix(scope): ...	patch
feat(scope): ...	minor
breaking change	major
docs/chore/ci without release significance	normally no release by themselves

Do not create fake fix or feat commits only to force a release.

Stable release side effects

The semantic-release configuration can:

• determine the next version;
• update CHANGELOG.md;
• publish npm;
• create/update the GitHub release;
• commit release-managed files back to the repository.

The stable job uses the repository's release credential for GitHub-side release/commit operations, while npm authentication remains OIDC-based.

Dist-tags

The intended tags are:

latest  stable release
canary  successful main-build preview

Historical beta or main tags may still exist in npm from earlier release models. They are not the current trunk release channels and should not be treated as authoritative for new automation.

Release checklist

Before stable publication:

1. confirm the desired main SHA is tested;
2. verify its canary if the change warrants consumer testing;
3. review generated package contents;
4. run the manual stable workflow from main;
5. approve the npm-prd environment when ready;
6. verify npm latest, provenance, GitHub release, and changelog after completion.