How to backport a change to a previous version with semantic-release for JS libraries

Add GitHub Action workflow file: manual-publish.yml

Ensure the repo has the following GitHub Action workflow file manual-publish.yml, which allows you to manually run an NPM publish from a specified branch in the repository.

[aside] There is likely an opportunity to make use of the shared GitHub Actions workflow files, e.g. the npm-publish..yml one: https://github.com/openedx/.github/blob/master/workflow-templates/npm-publish.yml

name: Manual Publish on: [workflow_dispatch] jobs: release: name: Manual Publish runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v2 with: fetch-depth: 0 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version-file: '.nvmrc' - name: Install dependencies run: npm ci - name: Validate package-lock.json changes run: make validate-no-uncommitted-package-lock-changes - name: Lint run: npm run lint - name: Test run: npm run test - name: i18n_extract run: npm run i18n_extract - name: Coverage uses: codecov/codecov-action@v2 - name: Build run: npm run build # NPM expects to be authenticated for publishing. This step will fail CI if NPM is not authenticated - name: Check NPM authentication run: | echo "//registry.npmjs.org/:_authToken=${{ secrets.SEMANTIC_RELEASE_NPM_TOKEN }}" >> .npmrc npm whoami - name: Release env: GITHUB_TOKEN: ${{ secrets.SEMANTIC_RELEASE_GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.SEMANTIC_RELEASE_NPM_TOKEN }} # `npm publish` relies on version specified in package.json file run: npm publish --tag {desired tag } # e.g., old-version

Create the backport changes

  1. Determine which version you need to backport to.

  2. Checkout the repository on a new branch based on the commit associated with that version’s commit SHA/Git tag.

  3. Make your desired changes for the backport.

  4. Update the package.json version field to be the desired version you want to publish.

  5. Commit your changes on your branch using a conventional commit type that will trigger an NPM publish with semantic-release (i.e., feat, fix).

  6. Push your branch with your commit to the remote (GitHub).

Releasing the backport changes

  1. Navigate to the repository’s GitHub Actions, e.g. https://github.com/edx/frontend-component-footer-edx/actions/workflows/manual-publish.yml

  2. Run the “Manual Publish” workflow from your branch.

3. Observe the action as it runs and/or verify it completes successfully.

4. Run npm view {npm package} versions --json (e.g., npm view webpack versions --json) to see all published versions of the NPM package. Useful as the https://npmjs.org website can often be cached for awhile on new publishes.

These steps do not include ensuring a Git tag and GitHub release are created for the backport version; only that an NPM release is created such that it is installable by consumers.

In the future, we may want to update documentation and build / improve upon these steps to ensure all Git tags and GitHub releases are created as well, perhaps by utilizing semantic-release in manual-publish.yml instead of npm publish.