Add semantic-release for automated versioning and npm publishing

[brian-smith-tcril]

Add semantic-release for automated versioning and npm publishing

Summary

This issue tracks the work to set up semantic-release for @openedx/frontend-base to automate versioning and npm publishing on merge to main.

Findings

Branch configuration

Semantic-release requires at least one non-prerelease release branch. Since main will produce 1.0.0-alpha.X prereleases for now, a placeholder branch needs to exist on the repo to satisfy this constraint. It won't produce releases unless commits are pushed to it. Branch protection should be added to placeholder to prevent accidental pushes that could trigger a stable release.

Tag format

Existing tags use a v prefix (v1.0.0-alpha.13), so tagFormat must be set to v${version}.

npm channel

The package currently publishes to the latest dist-tag. Semantic-release's prerelease branch model defaults the npm dist-tag to the branch name, so channel: "latest" must be set explicitly to preserve the current publishing behavior.

Git notes migration

Semantic-release uses refs/notes/semantic-release to track which npm channel each release was published to. The existing tags have no notes, so a one-time migration is needed:

git notes --ref semantic-release add -m '{"channels":["latest"]}' v1.0.0-alpha.13^{}
git push origin refs/notes/semantic-release

Note: ^{} is required to dereference the annotated tag to its commit — adding the note to the tag object itself won't work.

Proposed .releaserc

{
  "branches": [
    "placeholder",
    {
      "name": "main",
      "prerelease": "alpha",
      "channel": "latest"
    }
  ],
  "tagFormat": "v${version}",
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

Testing

This was tested on a fork of this repo (brian-smith-tcril/frontend-base) on the test-semantic-release branch, which mirrors main at the time of testing. The .releaserc used for testing can be found at this commit.

The .releaserc on that branch differs from the proposed config above in a few ways:

• test-semantic-release is used as the prerelease branch instead of main (so the dry run can execute from it)
• repositoryUrl is explicitly set to the fork via SSH (git@github.com:brian-smith-tcril/frontend-base.git) — this is needed locally because semantic-release auto-detects the repo URL from package.json, which points to the upstream openedx/frontend-base. Without overriding it, branch validation fails against the upstream where the test branches don't exist. SSH is used because the auth verification step (git push --dry-run) requires push access, and SSH keys are configured locally. In CI, a GH_TOKEN would handle this via HTTPS instead.
• @semantic-release/npm and @semantic-release/github plugins are omitted — these require NPM_TOKEN and GH_TOKEN respectively, which will be available in CI

The placeholder stable branch also exists on the fork.

To verify the git note on the fork:

git clone https://github.com/brian-smith-tcril/frontend-base.git
cd frontend-base
git fetch origin refs/notes/semantic-release:refs/notes/semantic-release
git notes --ref semantic-release show v1.0.0-alpha.13^{}
# Should output: {"channels":["latest"]}

Dry run result (run locally against the fork)

Found git tag v1.0.0-alpha.13 associated with version 1.0.0-alpha.13 on branch test-semantic-release
The next release version is 1.0.0-alpha.14

Remaining work

• Run git notes migration
• Create placeholder branch on this repo with branch protection enabled
• Add .releaserc
• Add release GitHub Actions workflow (using OPENEDX_SEMANTIC_RELEASE_GITHUB_TOKEN and NPM_TOKEN secrets)

Future work

When this package is ready for a stable 1.0.0 release:

• Remove prerelease and channel: "latest" from the main branch config so it produces stable versions
• Remove the placeholder branch from .releaserc and the repo (it's only needed while main is a prerelease branch)
• At that point, main will publish to latest as a proper stable release, and a separate prerelease branch (e.g. next) can be added for pre-release work

[brian-smith-tcril]

Log

frontend-base Semantic Release Setup - Work Log

Date: 2026-02-18

Objective

Set up semantic-release for @openedx/frontend-base.

---

Repo Setup

• Cloned from fork: brian-smith-tcril/frontend-base (fork of openedx/frontend-base)
• Changed upstream remote from SSH to HTTPS to prevent accidental pushes to openedx/frontend-base
• Pulled latest main from fork
• Created branch: test-semantic-release
• Pushed test-semantic-release to origin (required for semantic-release branch validation)
• Created placeholder branch on origin from main (required stable branch for semantic-release)

Current State of the Repo

• Version: 1.0.0-alpha.13 (in package.json)
• Versioning pattern: 1.0.0-alpha.X — will continue with semantic-release
• Tags: v1.0.0-alpha.0 through v1.0.0-alpha.13 (with v prefix — important!)
• npm publishing: to latest dist-tag (no named channel currently)
• Branch: main (not master)
• publishConfig: { "access": "public" } already set

Files Created

.releaserc

{
  "branches": [
    "placeholder",
    {
      "name": "main",
      "prerelease": "alpha",
      "channel": "latest"
    }
  ],
  "repositoryUrl": "git@github.com:brian-smith-tcril/frontend-base.git",
  "tagFormat": "v${version}",
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

Notes:

• repositoryUrl set to fork SSH URL for local auth (CI will use token-based HTTPS)
• tagFormat uses v prefix to match existing tags
• channel: "latest" on prerelease branches to keep publishing to npm latest dist-tag
• placeholder is a stub stable branch required by semantic-release (must have ≥1 non-prerelease branch)
• main is omitted from the final config until test-semantic-release testing is done

test-release.sh

Simple bash script to run a dry-run locally:

#!/bin/bash
set -e
npx semantic-release --dry-run

Run with: . /home/bsmith/.nvm/nvm.sh && nvm use && ./test-release.sh
(nvm must be sourced externally since nvm is a shell function, not a binary)

Git Notes Migration

Semantic-release uses refs/notes/semantic-release to track which npm channel each release was published to. The existing tags were created manually and had no notes, so semantic-release couldn't identify the last release.

Fix: Added a git note to the commit pointed to by v1.0.0-alpha.13:

git notes --ref semantic-release add -m '{"channels":["latest"]}' v1.0.0-alpha.13^{}
git push origin refs/notes/semantic-release --force

Key lessons:

• Notes must be added to the COMMIT (^{} dereferences an annotated tag to its commit), not the tag object itself
• channels: [null] means the default npm dist-tag — but this only works for release (non-prerelease) branches because prerelease branch channel always defaults to the branch name, never null
• channels: ["latest"] with explicit "channel": "latest" in branch config is the correct approach for publishing prerelease versions to the latest npm dist-tag

Dry Run Debugging Journey

Error 1: ERELEASEBRANCHES — current branch not in config

Running from test-semantic-release branch failed because semantic-release validates the current branch against configured branches. Fix: added test-semantic-release to .releaserc and pushed the branch to origin.

Error 2: repositoryUrl pointing to upstream

Semantic-release reads repositoryUrl from the repository field in package.json, which points to openedx/frontend-base. It then validated branches against the upstream repo (where test-semantic-release and placeholder don't exist). Fix: explicitly set repositoryUrl to the fork SSH URL in .releaserc.

Error 3: EPRERELEASEBRANCHES — duplicate prerelease identifiers

Both main and test-semantic-release had prerelease: "alpha". Each prerelease branch needs a unique prerelease identifier. Fix: removed main from the config for now (only needed during testing on test-semantic-release).

Error 4: EGITNOPERMISSION

Semantic-release runs git push --dry-run to verify push credentials even in dry-run mode. HTTPS URL required a token. Fix: use SSH URL for repositoryUrl locally.

Error 5: Token errors (ENOGHTOKEN, EINVALIDNPMTOKEN)

@semantic-release/npm and @semantic-release/github run verifyConditions even in dry-run. Fix: removed those plugins from .releaserc temporarily to focus on version determination.

Error 6: No git tag version found — tags not recognized

Tags existed and were reachable, but semantic-release couldn't determine the last release. Root causes (found by reading semantic-release source):

1. Initial note added to tag object hash (not the commit) — git rev-parse v1.0.0-alpha.13 returns the annotated tag object, not the commit. Must use v1.0.0-alpha.13^{}.
2. Note channel ("alpha") didn't match branch.channel — for a prerelease branch, channel defaults to the branch name, not the prerelease identifier. Required explicit "channel": "latest" and note {"channels":["latest"]}.

✅ Dry Run Result

Found git tag v1.0.0-alpha.13 associated with version 1.0.0-alpha.13 on branch test-semantic-release
The next release version is 1.0.0-alpha.14

[arbrandes]

No objections to the plan of action! Thanks!

[arbrandes]

Before we move ahead here, we should agree on the ADR.

[arbrandes]

The ADR has merged: we're unblocked!