How to make new xPack Logger releases
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 versionwebsite, 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
developmentbranch - Pull new changes
- If necessary, rebase the
masterbranch onto thedevelopmentbranch - If necessary, rebase the
websitebranch onto thedevelopmentbranch
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 outdatednpm updateor edit andnpm install- Repeat and possibly manually edit
package.jsonuntil 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.jsonfile - Use the new version, suffixed by
-pre, such as7.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
websitefolder and topREADME.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 theCHANGELOG.mdfile 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
developmentbranch npm run fix- If there are changes, commit all changes to the
developmentbranch 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/blogfolder:npm --prefix ~/Work/xpack/logger-ts.git/website run generate-website-blog-post - Fix the TODO in the front matter
descriptionproperty (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
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
developmentbranch - Execute the generate-website-commons npm script in the
website/package.jsonnpm --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
websitebranch - Run the
npm installcommand, to ensurepackage-lock.jsonis up to date - Rebase the
websitebranch onto thedevelopmentbranch (git rebase development) - Push the
websitebranch to GitHubinfoAt 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
developmentbranch - 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
masterbranch - Rebase the
masterbranch onto thedevelopmentbranch (git rebase development) - Push the
masterbranch to GitHub - Check out the
developmentbranch
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/loggerpackage
Credits to Shields IO for the badges.