Skip to main content

How to make new xpm releases

GitHub package.json version NPM Version CI on Push GitHub issues GitHub pulls CI on Push JavaScript Style Guide licence

This page is designed for maintainers of the xPack Project Manager project and provides documentation on creating new releases.

Prerequisites​

xpm is a portable Node.js project; development can be conducted on macOS, GNU/Linux and Windows (although some npm scripts must be executed within a Git Bash terminal).

The prerequisites are:

  • git
  • node >= 20.0.0
  • npm

To ensure compatibility with older node versions, it is preferable to revert to an older one:

nvm use --lts 20
code

Obtain project sources​

The project is hosted on GitHub:

Branches

This project utilises multiple branches:

  • master, containing the latest stable version (default)
  • development, containing the current development version
  • website, containing the current website content; pushes to this branch automatically trigger publication of the main website
  • webpreview, containing the current preview website content; pushes to this branch automatically trigger publication of the preview website

All development is conducted in the development branch, and contributions via Pull Requests should be directed to this branch.

When new releases are published, the development branch is merged into master.

To clone the stable branch (master), execute the following commands in a terminal (on Windows use the Git Bash console):

rm -rf ~/Work/xpack/xpm-js.git && \
mkdir -p ~/Work/xpack && \
git clone \
  --branch master \
  https://github.com/xpack/xpm-js.git \
  ~/Work/xpack/xpm-js.git
For development purposes, clone the development branch.
rm -rf ~/Work/xpack/xpm-js.git && \
mkdir -p ~/Work/xpack && \
git clone \
  --branch development \
  https://github.com/xpack/xpm-js.git \
  ~/Work/xpack/xpm-js.git

Alternatively, if the repository has already been cloned:

git -C ~/Work/xpack/xpm-js.git pull
tip

To contribute Pull Requests, fork the project and ensure the Copy the master branch only is disabled.

Utilise the development branch and ensure you contribute the Pull Requests back to the development branch.

During development, it is convenient to maintain a writable instance of the source code to enable changes in parallel with the parent project.

To facilitate the use of a writable instance of this source code in other projects, add a link from the user's global npm store to this local development folder:

npm --prefix ~/Work/xpack/xpm-js.git link

And in the projects referring it:

npm link xpm

Release schedule​

There are no fixed releases.

Prepare a new release​

Check Git​

In the xpack/xpm-js Git repository:

  • Switch to the development branch
  • Pull new changes
  • If necessary, merge the master branch
  • If necessary, merge the website branch
caution

This is critically important; otherwise you will release the previous content again!

The master branch should remain unchanged since the previous release and will be updated when the new release is published.

Update npm packages​

note

This package is also utilised by the VS Code extension and, until VS Code accepts ESM dependencies, it must be maintained as a legacy CommonJS dependency.

  • npm outdated
  • npm update or edit and npm install
  • Repeat and possibly manually edit package.json until everything is up to date
  • Commit the changes
Dependencies packages

dependencies:

devDependencies:

Increase the version and update the top package.json​

As required by npm projects, this one also utilises SemVer.

  • Determine the next version (such as 0.21.4)
  • Update the version in the top package.json file
  • Use the new version, suffixed by -pre, such as 0.21.4-pre.

Update the websiteConfig (if necessary)​

Check and possibly update the release-specific properties (like the release date) within website/package.json.

Generate the website commons​

Execute the generate-website-commons npm script from website/package.json within the project folder.

npm --prefix ~/Work/xpack/xpm-js.git/website run generate-website-commons

Commit the website changes​

  • Stage the website folder and top README.md
  • Commit with the message re-generate website commons

Start the local web server​

Execute the npm script clear followed by start in the website sub-project, or execute the following within the project folder:

npm --prefix ~/Work/xpack/xpm-js.git/website run clear
npm --prefix ~/Work/xpack/xpm-js.git/website run start

Navigate to the Maintainer Info page, the Start the local web server section.

Fix possible open issues​

Check GitHub Issues and Pull Requests:

and resolve them; assign them to a milestone (such as 0.21.4).

Update CHANGELOG.md​

  • Open the CHANGELOG.md file
  • Check if all previously fixed issues are included
  • Check the latest commits npm run git-log; if necessary, copy/paste lines, group by dates and edit them using the regular expressions below
  • To convert the dates into headings, change from: 


    ([0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) [*]
    to: 


    ## $1

    *
  • To remove the remaining dates, change from: 
    ^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] [*]
    to: 
    *
  • Add a new entry such as * v0.21.4 prepared
  • Commit with the message prepare v0.21.4

Prepare the release​

  • Switch to the development branch
  • npm run fix
  • If there are changes, commit all changes to the development branch
  • npm run test
  • Check the latest commits npm run git-log
  • Update CHANGELOG.md, add a line such as * v0.21.4 published on npmjs.com
  • Commit with the message CHANGELOG: publish npm v0.21.4
  • Check the list of files included in the npm package: 
    npm run npm-pack
  • Possibly update .npmignore

Set the new version​

Execute the following within the project folder:

npm version 0.21.4

The postversion npm script should also update tags via git push origin --tags; this should also trigger CI tests.

CI tests​

Prepare a new blog post​

  • Check and possibly update the website/blog/_templates/blog-post*-release-liquid.mdx
  • Execute the generate-website-blog-post npm script; this will add a file to the website/blog folder: 
    npm --prefix ~/Work/xpack/xpm-js.git/website run generate-website-blog-post
  • Fix the TODO in the front matter description property (select maintenance vs. new release)
  • Fix the TODO in the summary (select maintenance vs. new release)
  • Add entries in the Bug fixes; utilise the following syntax 
    - [[#N](https://github.com/xpack/xpm-js/issues/N)]:
  • Commit with the message website: blog post release 0.21.4 published

Publish the release to npmjs.com​

Execute the following command within the project folder:

npm publish --tag next
tip

When publishing for the first time, utilise --access public.

After a few moments, the version will be visible at npmjs.com, under the Versions tab.

Manual install test​

Test if the package can be installed globally:

npm install --location=global xpm@next

Validate the website content through a local build using the npm build script:

npm run build

Prepare the website​

The documentation site is built using Docusaurus and published on the project GitHub Pages.

  • Switch to the development branch
  • Execute the website-generate-commons npm script in the website/package.json 
    npm --prefix ~/Work/xpack/xpm-js.git/website run website-generate-commons
  • Commit all changes

Build the static website locally​

Validate the website content by performing a local build using the npm build script:

npm --prefix ~/Work/xpack/xpm-js.git/website run build

Resolve any broken links that may be identified during the build process.

Publish the website​

The website deployment is performed automatically when pushing to the website branch, utilising a dedicated workflow in GitHub Actions.

  • Open https://xpack.github.io/xpm/docs/maintainer/#publish-the-website in a separate window
  • Stop the local web server
  • Switch to the website branch
  • Merge the development branch into the website branch
  • Push the website branch to GitHub
    info

    At this point, an automated GitHub Action will generate and publish the website.

  • Check out the development branch
  • Wait for the publication to complete
  • Refresh the web page
  • The new release blog post is available at https://xpack.github.io/xpm/blog/
  • Record the post URL, as it must be used to update the release page and the X/Twitter announcement

The website branch may be subsequently updated, provided the version in package.json remains unchanged.

Verify the result at https://xpack.github.io/xpm/.

Final updates​

Update the stable branch​

In this Git repository:

  • Select the master branch
  • Merge the development branch into the master branch
  • Push the master branch to GitHub
  • Check out the development branch
note

Avoid further updates to the master branch until the next release.

Close possible open issues​

Check GitHub Issues and Pull Requests:

Close those that have been addressed.

Close milestone​

In https://github.com/xpack/xpm-js/milestones:

  • Close the current milestone.

Check npm package tags​

Execute the following command in a terminal:

npm dist-tag ls xpm

Tag the npm package as latest​

When the release is considered stable, promote it as latest:

npm dist-tag add xpm@0.21.4 latest

Check the result:

npm dist-tag ls xpm

Should the release prove problematic and require unpublishing:

npm unpublish xpm@0.21.4

Share on X/Twitter​

  • In a separate browser window, open X/Twitter
  • Utilising the @xpack_project account
  • Paste the release name such as xPack Project Manager v0.21.4 released
  • Paste the link to the web page release
  • Click the Tweet button

Analytics​

  • npmjs.com xpm package
    • latest release, per month NPM Version NPM Downloads
    • all releases NPM Downloads

Credits to Shields IO for the badges.