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-versionCreate the backport changes
Determine which version you need to backport to.
Checkout the repository on a new branch based on the commit associated with that version’s commit SHA/Git tag.
Make your desired changes for the backport.
Update the package.json
versionfield to be the desired version you want to publish.Commit your changes on your branch using a conventional commit type that will trigger an NPM publish with semantic-release (i.e.,
feat,fix).Push your branch with your commit to the remote (GitHub).
Releasing the backport changes
Navigate to the repository’s GitHub Actions, e.g. https://github.com/edx/frontend-component-footer-edx/actions/workflows/manual-publish.yml
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.