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

xcdl is a portable Node.js module; development can be performed 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:

https://github.com/xpack/xcdl-cli-ts.git

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

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).

Dependencies packages

dependencies:

https://www.npmjs.com/package/@ilg/cli-start-options

devDependencies:

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.

Update the website commons

Run the website-generate-commons script in the top package.json; this will also update the top README.md file.

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 run clean
npm 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
push all changes to GitHub

Set the new version

npm version 2.0.0

CI tests

the postversion npm script should also update tags via git push origin --tags; this should trigger CI
wait for CI tests to complete
check https://github.com/xpack/xcdl-cli-ts/actions

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

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 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 script in the top package.json
commit all changes
run the build script in website/package.json
fix any broken links, if any

Publish the website

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

switch to the website branch
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 new release blog post is in https://xpack.github.io/xcdl-cli-ts/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/xcdl-preview/.

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/xcdl-cli-ts/milestones:

close the current milestone.

Check npm package tags

npm dist-tag ls xcdl

Tag the npm package as `latest`

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

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

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
- all releases

Credit to Shields IO for the badges.

Prerequisites​

Get project sources​

Release schedule​

Prepare the new releases​

Check Git​

Update npm packages​

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

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

Update the website commons​

Start the local web server​

Fix possible open issues​

Update CHANGELOG.md​

Prepare the release​

Set the new version​

CI tests​

Prepare a new blog post​

Publish the release to npmjs.com​

Manual install test​

Prepare the website​

Publish the website​

Final updates​

Update the master branch​

Close milestone​

Check npm package tags​

Tag the npm package as latest​

Share on X/Twitter​

Analytics​

Useful links​