Skip to main content

GitHub package.json version npm (scoped) license CI on Push GitHub issues GitHub pulls TS-Standard - TypeScript Standard Style Guide

How to make new xcdl releases

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

Prerequisites​

The xPack Component Manager is a portable Node.js project, and development can be performed on macOS, GNU/Linux and even Windows (although some npm scripts require bash).

The prerequisites are:

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

The project uses two branches:

  • master, with the latest stable version (default)
  • development, with the current development version

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

mkdir ~/Work/npm-packages && cd ~/Work/npm-packages
git clone https://github.com/xpack/xcdl-cli-ts.git xcdl-cli-ts.git

For development purposes, clone the development branch:

mkdir ~/Work/npm-packages && cd ~/Work/npm-packages
git clone \
  --branch development \
  https://github.com/xpack/xcdl-cli-ts.git xcdl-cli-ts.git

Or, if the repo was already cloned:

git -C ~/Work/npm-packages/xcdl-cli-ts.git pull

Release schedule​

There are no fixed releases.

Prepare the new releases​

Check Git​

In the xpack/xcdl-cli-ts 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 the next steps will build again the previous release!

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

Keep:

  • @types/node locked to latest that still matches the oldest supported node (18).

Increase the version and update it in the top package.json​

As required by npm modules, this one also uses SemVer.

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

Update the websiteConfig in top package.json (if necessary)​

Check and possibly update the websiteConfig.

Start the local web server​

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

npm --prefix ~/Work/npm-packages/xcdl-cli-ts.git/website run clean
npm --prefix ~/Work/npm-packages/xcdl-cli-ts.git/website run start

Navigate to the Maintainer Info page, the Fix possible open issues section.

Fix possible open issues​

Check GitHub Issues and Pull Requests:

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

Update CHANGELOG.md​

  • open the CHANGELOG.md file

  • check if all previous fixed issues are in

  • check the latest commits xpm 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 * v2.0.0 prepared
  • commit with a message like prepare v2.0.0

Prepare the release​

  • terminate all running tasks (Terminal → Terminate Task...)
  • switch to the development branch
  • commit everything
  • npm run fix
  • if there are changes, commit all changes into the development branch
  • npm run test
  • npm run pack; check the list of packaged files, possibly update .npmignore
npm version 2.0.0
  • push all changes to GitHub

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 --prefix ~/Work/npm-packages/xcdl-cli-ts.git/website run generate-website-blog-post
  • edit the front matter properties
  • select the correct summary
  • commit with website: blog post release 2.0.0 published
  • push the development branch

Publish the release to npmjs.com​

npm publish --tag next
  • when publishing for the first time, use:
npm publish --access public

After a few moments the version will be visible at xcdl Versions.

Manual install test​

Test if the package can be installed globally:

npm install ----location=global xcdl@next

Validate the web site content in a local build via the npm build script:

npm --prefix ~/Work/npm-packages/xcdl-cli-ts.git/website run build

Publish the website​

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

The Web site deployment is performed automatically when pushing to the master branch, by a dedicated workflow in GitHub Actions.

  • switch to the development branch
  • run the website-generate-commons script in the top package.json
  • commit all changes
  • run the build script in website/package.json
  • merge the development branch into the website branch
  • push the website branch to GitHub

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

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

Final updates​

Update the master branch​

In this Git repo:

  • select the master branch
  • merge the development branch into the master branch
  • push the master branch to GitHub

Close milestone​

In https://github.com/xpack/xpm-liquid-ts/milestones:

  • close the current milestone.

Tag the npm package as latest​

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

  • npm dist-tag ls xcdl
  • npm dist-tag add xcdl@2.0.0 latest
  • npm dist-tag ls xcdl

Share on X/Twitter​

  • in a separate browser windows, open X/Twitter
  • using the @xpack_project account
  • paste the release name like xPack xpm v0.19.4 released
  • paste the link to the Web page release
  • click the Tweet button

Analytics​

  • npmjs.com xcdl package
    • latest release, per month npm (scoped) npm
    • all releases npm

Credit to Shields IO for the badges.