Skip to main content

How to make new xPack Logger releases

GitHub package.json version NPM Version GitHub issues GitHub pulls CI on Push TypeScript ESLint licence Website

This page is for the maintainers of the xPack Logger project, and describes how to create new releases.

Prerequisites​

@xpack/logger is a portable Node.js module; development can be conducted on macOS, GNU/Linux, and Windows.

The prerequisites are:

  • git
  • node >= 22.12
  • npm

To check the compatibility with the oldest supported node version, switch to it:

nvm use --lts 22
code

Obtain project sources​

The project is hosted on GitHub:

Branches

This project uses 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

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 master branch is rebased onto development.

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

rm -rf ~/Work/xpack/logger-ts.git && \
mkdir -p ~/Work/xpack && \
git clone \
--branch development \
https://github.com/xpack/logger-ts.git \
~/Work/xpack/logger-ts.git

Alternatively, if the repository has already been cloned:

git -C ~/Work/xpack/logger-ts.git pull
Obtain the writable helper sources (optional, for development purposes)

The project has a dependency on a common helper, which is normally installed as a read-only dependency; for development purposes, to enable modifications to the scripts located within the helper, clone the master branch and link it to the global packages location:

rm -rf ~/Work/xpack/npm-packages-helper.git && \
mkdir -p ~/Work/xpack && \
git clone \
--branch master \
https://github.com/xpack/npm-packages-helper.git \
~/Work/xpack/npm-packages-helper.git

Alternatively, if the repository has already been cloned:

git -C ~/Work/xpack/npm-packages-helper.git pull

Tell the global npm configuration where the local development folder is located (link the project):

npm --prefix ~/Work/xpack/npm-packages-helper.git link

Similarly, for the website helper, clone the master branch and link it to the global packages location:

rm -rf ~/Work/xpacks/docusaurus-template-liquid.git && \
mkdir -p ~/Work/xpacks/docusaurus-template-liquid && \
git clone \
--branch master \
https://github.com/xpacks/docusaurus-template-liquid.git \
~/Work/xpacks/docusaurus-template-liquid.git

Alternatively, if the repository has already been cloned:

git -C ~/Work/xpacks/docusaurus-template-liquid.git pull

Tell the global npm configuration where the local development folder is located (link the project):

npm --prefix ~/Work/xpacks/docusaurus-template-liquid.git link

Release schedule​

There are no fixed releases.

Prepare a new release​

Check Git​

In the xpack/logger-ts Git repository:

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

Do not skip these steps; otherwise the previous content is released again.

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

Update npm packages​

  • 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 the version of @types/node in sync with the Node.js version specified in package.json (currently 22.12).

Increase the version and update the top package.json​

The project uses SemVer, as required by npm.

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

Update the website configuration (if necessary)​

Check and possibly update the properties of the website configuration within website/config/website-templates.json. The version of the release is taken from the top 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/logger-ts.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/logger-ts.git/website run clear
npm --prefix ~/Work/xpack/logger-ts.git/website run start

Navigate to the Maintainer's Guide page, the Start the local web server section.

Fix the open issues​

Check GitHub Issues and Pull Requests:

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

Update CHANGELOG.md​

  • Run npm run update-changelog; this should update the CHANGELOG.md file with the latest changes
  • Add a new entry such as * v7.0.0 prepared
  • Commit with the message prepare v7.0.0

Prepare the release​

  • Terminate all running tasks (Terminal → Terminate Task...)
  • 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 with npm run git-log
  • Update CHANGELOG.md, add a line such as * v7.0.0 published on npmjs.com
  • Commit with the message CHANGELOG: publish npm v7.0.0
  • Check the list of files included in the npm package:
    npm run npm-pack
  • If the list is not correct, fix .npmignore; since this file is generated, change its template in the helper project, and regenerate it with the generate-top-commons npm script

Set the new version​

Execute the following within the project folder:

npm version 7.0.0

The postversion npm script pushes the commits and the tags to GitHub, which triggers the CI tests.

CI tests​

  • Wait for CI tests to complete
  • Check CI on Push workflow

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/logger-ts.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)
  • In the relevant sections (Major changes, Bug fixes, Enhancements), replace the - None. placeholder with entries; to link to GitHub issues, use:
    - [[#N](https://github.com/xpack/logger-ts/issues/N)]: Title
  • If compatibility notices were added for the release, move their details from the Getting Started category to a Detailed changes section at the end of the blog post, with the {#details} anchor (## Detailed changes {#details}), and replace the notice with a summary of no more than three sentences, which links to that section (/blog/YYYY/MM/DD/<post>/#details)
  • Commit with the message website: blog post release 7.0.0 published

Publish the release to npmjs.com​

Log in to npmjs.com:

npm login

Execute the following command within the project folder:

npm publish --tag test
tip

When publishing for the first time, use --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 in a project:

rm -rf ~/tmp/logger-test && mkdir ~/tmp/logger-test && cd ~/tmp/logger-test
npm init --yes
npm install @xpack/logger@test

Prepare the website​

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

  • Switch to the development branch
  • Execute the generate-website-commons npm script in the website/package.json
    npm --prefix ~/Work/xpack/logger-ts.git/website run generate-website-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/logger-ts.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, using a dedicated workflow in GitHub Actions.

  • Open https://xpack.github.io/logger-ts/docs/maintainer/#publish-the-website in a separate window
  • Stop the local web server
  • Switch to the website branch
  • Run the npm install command, to ensure package-lock.json is up to date
  • Rebase the website branch onto the development branch (git rebase development)
  • Push the website branch to GitHub
    info

    At this point, an automated forwarding GitHub Action will trigger a GitHub Action in the separate project to generate and publish the website.

  • Check out the development branch
  • Wait for the publication to complete
  • Check the GitHub Pages workflow
  • Refresh the web page
  • Open the new release blog post, available at https://xpack.github.io/logger-ts/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/logger-ts/.

Final updates​

Update the stable branch​

In this Git repository:

  • Select the master branch
  • Rebase the master branch onto the development branch (git rebase development)
  • Push the master branch to GitHub
  • Check out the development branch
note

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

Close the open issues​

Check GitHub Issues and Pull Requests:

Close those that have been addressed.

Close milestone​

In https://github.com/xpack/logger-ts/milestones:

  • Close the current milestone

Check npm package tags​

Execute the following command in a terminal:

npm dist-tag ls @xpack/logger

Tag the npm package as latest​

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

npm dist-tag add @xpack/logger@7.0.0 latest

Check the result:

npm dist-tag ls @xpack/logger

Should the release prove problematic, deprecate it, so that the users get a warning when they install it; the version remains available:

npm deprecate @xpack/logger@7.0.0 "<reason>"

npm allows unpublishing a version only within 72 hours of its publication, so this should be used only for a release published by mistake:

npm unpublish @xpack/logger@7.0.0

Analytics​

  • npmjs.com @xpack/logger package
    • latest version NPM Version
    • last month downloads NPM Downloads
    • total downloads, all releases NPM Downloads

Credits to Shields IO for the badges.