dc/.agents/docs/releases-and-changelog.md

Releases and the CHANGELOG

Do not edit CHANGELOG.md by hand, and do not bump the version in package.json yourself. Both are generated automatically by the release pipeline. Manual edits produce duplicate/colliding version sections and merge conflicts, and they are pointless because the next release overwrites them anyway.

How releases work

Releases are driven by semantic-release from the release job in .gitea/workflows/release.yaml, which runs on every push to main (after the build/test jobs pass). The configuration lives in .releaserc at the repo root.

The plugin chain (.releaserc plugins) does the following on each release:

1. @semantic-release/commit-analyzer - inspects Conventional Commit messages since the last tag to decide the next semantic version (fix: -> patch, feat: -> minor, breaking change -> major).
2. @semantic-release/release-notes-generator - builds the release notes from those commits.
3. @semantic-release/changelog - writes the new section into CHANGELOG.md.
4. @semantic-release/npm - updates the version in package.json (it does not publish; the package is private).
5. @semantic-release/git - commits CHANGELOG.md and package.json back to main as chore(release): <version> [skip ci] and tags it.
6. @saithodev/semantic-release-gitea - creates the Gitea release.

The build assets (frontend zip, SAS 9 / Viya / SASjs Server deployment files) are attached to the release afterwards by the workflow's own Upload assets to release step using the Gitea API (curl), not by the plugin. Before creating the release the workflow first runs semantic-release --dry-run and aborts the job if there are no releasable changes since the last tag.

Because the changelog entry and version bump are committed by the pipeline (step 5), they must not exist in your working tree beforehand. If they do, the release commit collides with them.

What this means for you

• Never add, remove, or reorder entries in CHANGELOG.md.
• Never change version in package.json.
• Control what appears in the changelog through your commit messages (Conventional Commits: fix:, feat:, feat!:/BREAKING CHANGE:, plus scopes like fix(editor): ...). The scope and description become the changelog line.
• If you find hand-written entries in CHANGELOG.md in the working tree, revert them (git checkout CHANGELOG.md).
• CI does not use any local release script - the pipeline installs and runs semantic-release directly.