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 license

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

Prerequisites​

xpm is a portable Node.js module; development can be carried out on macOS, GNU/Linux and even Windows (although some npm scripts must be executed in a Git Bash terminal).

The prerequisites are:

  • git
  • node >= 18.0.0
  • npm

To ensure compatibility with older node, preferably revert to an older one:

nvm use --lts 18
code

Get project sources​

The project is hosted on GitHub:

Branches

The project uses multiple branches:

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

All development is done 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), run 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

Or, if the repo was already cloned:

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

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

Use the xpack-development branch and be sure you contribute the Pull Requests back to the xpack-development branch.

During development, it is convenient to have a writable instance of the module to make changes in parallel with the parent project.

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

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

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 repo:

  • switch to the development branch
  • pull new changes
  • if necessary, merge the master branch
  • if necessary, merge the website branch
caution

This is really important, otherwise you will release the previous content again!

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

Update npm packages​

note

This package is also used by the VS Code extension and, until VS Code will accept ESM dependencies, it must be kept 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 modules, this one also uses SemVer.

  • determine the next version (like 0.20.8)
  • update the version in the top package.json file
  • use the new version, suffixed by -pre, like 0.20.8-pre.

Update the websiteConfig (if necessary)​

Check and possibly update the release specific properties (if any) in website/package.json.

Update the website commons​

Run the generate-website-commons npm script from website/package.json in the project folder.

npm run generate-website-commons -C website

Start the local web server​

Execute the npm script clean then start in the website sub-project, or run the following in the project folder:

npm run clean -C website
npm run start -C website

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

Fix possible open issues​

Check GitHub Issues and Pull Requests:

and fix them; assign them to a milestone (like 0.20.8).

Update CHANGELOG.md​

  • open the CHANGELOG.md file
  • check if all previous fixed issues are in
  • check the latest commits npm run git-log; if necessary, copy/paste lines, group by dates and edit them using the below regular expressions
  • to turn 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 rest of the dates, change from: 
    ^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] [*]
    to: 
    *
  • add a new entry like * v0.20.8 prepared
  • commit with the message prepare v0.20.8

Prepare the release​

  • switch to the development branch- npm run fix
  • if there are changes, commit all changes into the development branch- npm run test
  • check the latest commits npm run git-log
  • update CHANGELOG.md, add a line like * v0.20.8 published on npmjs.com
  • commit with the message CHANGELOG: publish npm v0.20.8
  • check the list of files included in the npm package: 
    npm run pack
  • possibly update .npmignore

Set the new version​

Run the following in the project folder:

npm version 0.20.8

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
  • run the generate-website-blog-post npm script; this will add a file in the website/blog folder: 
    npm run generate-website-blog-post -C website
  • edit the front matter properties (the description property)
  • select the correct summary (maintenance vs. new release)
  • add entries in the Bug fixes; use the following syntax 
    - [[#N](https://github.com/xpack/xpm-js/issues/N)]:
  • commit with the message website: blog post release 0.20.8 published

Publish the release to npmjs.com​

Run the following command in the project folder:

npm publish --tag next
tip

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

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

Manual install test​

Test if the package can be installed globally:

npm install --location=global xpm@next

Validate the website content in a local build via the npm build script:

npm run build

Prepare the website​

The documentation site is built with Docusaurus and published in the project GitHub Pages.

  • switch to the development branch
  • run the website-generate-commons npm script in the website/package.json 
    npm run website-generate-commons -C website
  • commit all changes

Build the static website locally​

Validate the website content in a local build via the npm build script:

npm run build -C website

Fix any broken links, if any.

Publish the website​

The website deployment is performed automatically when pushing to the website branch, by 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 moment an automated GitHub Action will generate and publish the website.

  • checkout the development branch
  • wait for the publish to complete
  • refresh the web page
  • the new release blog post is in https://xpack.github.io/xpm/blog/
  • remember the post URL, since it must be used to update the release page and the X/Twitter announcement

The website branch may be subsequently updated, as long as the version in package.json is not changed.

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

Final updates​

Update the stable branch​

In this Git repo:

  • select the master branch
  • merge the development branch into the master branch
  • push the master branch to GitHub
  • checkout 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 were addressed.

Close milestone​

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

  • close the current milestone.

Check npm package tags​

Run 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.20.8 latest

Check the result:

npm dist-tag ls xpm

In case the release proves problematic and needs to be unpublished:

npm unpublish xpm@0.20.8

Share on X/Twitter​

  • in a separate browser windows, open X/Twitter
  • using the @xpack_project account
  • paste the release name like xPack Project Manager v0.20.8 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

Credit to Shields IO for the badges.