Skip to main content

How to make new µTest++ Testing Framework releases

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

This page is for the maintainers of the µTest++ Testing Framework project, and describes how to create new releases.

Prerequisites​

@micro-os-plus/micro-test-plus is an xpm package that provides a C++ source code library; development can be conducted on macOS, GNU/Linux, and Windows.

The prerequisites are:

  • git
  • node >= 22.12
  • npm

To execute the native tests with the system tools, a C++ development environment is required. On macOS, install Command Line Tools; on Ubuntu, install build-essential.

For details on installing the prerequisites, please refer to the Prerequisites page.

Obtain project sources​

The project is hosted on GitHub:

Branches

This project uses multiple branches:

  • master, not actively used
  • xpack, containing the latest stable version (default)
  • xpack-development, containing the current development version
  • website, containing the current website content; pushes to this branch automatically trigger publication of the main website
  • webpreview, containing the current preview website content; pushes to this branch automatically trigger publication of the preview website

All development is conducted in the xpack-development branch, and contributions via Pull Requests should be directed to this branch.

When new releases are published, the xpack branch is rebased onto xpack-development.

To contribute Pull Requests, fork the project and make sure the Copy the xpack branch only option is disabled, so that the xpack-development branch is also copied and can be used for contributions.

tip

After making changes, direct the Pull Requests to the xpack-development branch.

The next step would normally be to clone the forked repository.

However, if Pull Requests are not intended, directly clone the xpack-development branch of the original repository:

rm -rf ~/Work/micro-os-plus/micro-test-plus-xpack.git && \
mkdir -p ~/Work/micro-os-plus && \
git clone \
  --branch xpack-development \
  https://github.com/micro-os-plus/micro-test-plus-xpack.git \
  ~/Work/micro-os-plus/micro-test-plus-xpack.git

If the repository has already been cloned, update it with:

git -C ~/Work/micro-os-plus/micro-test-plus-xpack.git pull
Add links for development

By default, to prevent inadvertent changes, xpm dependencies are installed in read-only folders with filtered content; developer-related files are not installed

However, during development, it is convenient to maintain a writable instance of the code to enable changes in parallel with the parent project.

Therefore, during development, if this project is used as a dependency of another project, it is convenient to use the full version of the project and make changes directly in the local development folder.

The mechanism xpm uses for this is called linking, and is similar to the npm link mechanism.

The process has two steps:

  1. Tell the global xpm configuration where the local development folder is located.
  2. Tell the top project to use the linked development folder instead of the installed read-only dependency.

The first step requires executing the xpm link command in the local development folder, as shown below:

xpm link -C ~/Work/micro-os-plus/micro-test-plus-xpack.git

The result is the creation of a symbolic link in the global xPacks store pointing to the local development folder.

For example:

% ls -l xPacks/micro-os-plus/micro-test-plus-xpack/.link
lrwxr-xr-x  1 ilg  staff  75 Oct 26 21:57 xPacks/micro-os-plus/micro-test-plus-xpack/.link -> /Users/ilg/Work/micro-os-plus/micro-test-plus-xpack.git

For the second step, in the top project, instead of adding the dependency by installing it, run the command to link it:

xpm link @micro-os-plus/micro-test-plus
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 xpack-development branch and link it to the global packages location:

rm -rf ~/Work/micro-os-plus/build-helper-xpack.git && \
mkdir -p ~/Work/micro-os-plus && \
git clone \
  --branch xpack-development \
  https://github.com/micro-os-plus/build-helper-xpack.git \
  ~/Work/micro-os-plus/build-helper-xpack.git

Alternatively, if the repository has already been cloned:

git -C ~/Work/micro-os-plus/build-helper-xpack.git pull

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

npm --prefix ~/Work/micro-os-plus/build-helper-xpack.git link

Code formatting​

For formatting style, the library employs a .clang-format configuration file based on the GNU style, in the maintenance/config folder.

The source files are formatted with the clang-format xpm action, which runs clang-format with that configuration on the C and C++ files of the project:

xpm run clang-format -C ~/Work/micro-os-plus/micro-test-plus-xpack.git

Similarly, the cmake-format and jsonc-format actions format the CMake and the JSONC files.

info

The clang-format program is installed by xpm install, as a development dependency of the project, in the xpacks/.bin folder.

tip

Reformat the modified source files before committing them.

Release schedule​

The project employs a continuous release strategy, with updates published as development progresses, rather than following a fixed release schedule.

Prepare a new release​

Check Git​

In the micro-os-plus/micro-test-plus-xpack Git repository:

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

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

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

Increase the version and update the top package.json​

The project uses SemVer, as required by npm.

  • Determine the next version (such as 6.0.0)
  • Update the version in the top package.json file
  • Use the new version, suffixed by -pre, such as 6.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/micro-os-plus/micro-test-plus-xpack.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/micro-os-plus/micro-test-plus-xpack.git/website run clear
npm --prefix ~/Work/micro-os-plus/micro-test-plus-xpack.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 6.0.0).

Add a compatibility notice​

For the major and minor releases, add a compatibility notice for the version under development, on the Compatibility notices page, in the Getting Started category (for example v6.0 (not yet released)), and update it with each issue and each commit that breaks the compatibility of existing code, changes its behaviour, deprecates a definition, or adds a new feature:

  • group the entries by kind: new features, deprecated definitions, changes that break the compilation, and changes of behaviour;
  • for each entry, give the old and the new names, and what the applications must change;
  • do not postpone the entries to the release, because the details are soon forgotten.

The patch releases do not need a compatibility notice.

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 * v6.0.0 prepared
  • Commit with the message prepare v6.0.0

Reformat source files​

  • Reformat the source files that were changed, with the clang-format xpm action (see Code formatting)
  • Commit and push

Manual tests​

There are predefined xpm actions available to manually execute various tests on the local development machine.

Start with a clean-up (not needed after the initial git clone):

npm --prefix ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests install
npm --prefix ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests run deep-clean
npm --prefix ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests install
tip

During the initial execution, the installation step may require a considerable amount of time, as it needs to download the toolchain archives, which can be relatively large, up to several hundred megabytes.

To execute the tests with the system compiler (usually not available on Windows):

xpm run install -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests
xpm run test -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests

To execute a selection of tests with the latest versions of toolchains:

xpm run install-selected -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests
xpm run test-selected -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests

To execute all tests with the latest versions of toolchains:

xpm run install-latest -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests
xpm run test-latest -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests

To execute all tests with all toolchain versions:

xpm run install-all -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests
xpm run test-all -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests

To build the physical boards binaries with the latest versions of toolchains:

xpm run install-boards -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests
xpm run build-boards -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests

Clean-ups​

Executing all tests may require several gigabytes of space.

To clean up the tests folder, use:

npm --prefix ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests install
npm --prefix ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests run deep-clean

A considerable amount of space may also be used by the toolchains. When no longer required, they can be removed with xpm uninstall.

xpm clean-ups

For a complete clean-up, note that xpm uses two folders:

  • %APPDATA%\xPacks
  • %LOCALAPPDATA%\Caches\xPacks

They can be removed at any time and space reclaimed; xpm will recreate them during new installations.

However, the projects that link to the user's global xPacks store will have broken links.

Prepare the release​

  • Switch to the xpack-development branch
  • If there are changes, commit all changes to the xpack-development branch
  • Check the latest commits with npm run git-log
  • Update CHANGELOG.md, add a line such as * v6.0.0 published on npmjs.com
  • Commit with the message CHANGELOG: publish npm v6.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 6.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

Test on all platforms​

In addition, it is possible to manually trigger a test-all job, which executes all available tests, on all supported platforms.

For this:

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/micro-os-plus/micro-test-plus-xpack.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/micro-os-plus/micro-test-plus-xpack/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 6.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.

Publish the website​

Regenerate the Doxygen pages​

Execute the generate-website-doxygen npm script:

npm --prefix ~/Work/micro-os-plus/micro-test-plus-xpack.git/website run generate-website-doxygen

At present, the doxygen program must be installed on the host, as it is not available as an xpm dependency.

With the current configuration, the static HTML pages are generated within the website/static/doxygen folder and converted to Docusaurus Markdown in docs/api.

Prepare the website​

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

  • Switch to the xpack-development branch
  • Execute the generate-website-commons npm script in the website/package.json 
    npm --prefix ~/Work/micro-os-plus/micro-test-plus-xpack.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/micro-os-plus/micro-test-plus-xpack.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://micro-os-plus.github.io/micro-test-plus-xpack/docs/maintainer/#publish-the-website in a separate window
  • Stop the local web server
  • Switch to the webpreview branch
  • Rebase the webpreview branch onto the xpack-development branch (git rebase xpack-development)
  • Push the webpreview branch to GitHub
    info

    At this point, an automated GitHub Action will generate and publish the preview website.

  • 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 xpack-development branch (git rebase xpack-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 xpack-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://micro-os-plus.github.io/micro-test-plus-xpack/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://micro-os-plus.github.io/micro-test-plus-xpack/.

Final updates​

Update the stable branch​

In this Git repository:

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

Avoid further updates to the xpack 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/micro-os-plus/micro-test-plus-xpack/milestones:

  • Close the current milestone

Check npm package tags​

Execute the following command in a terminal:

npm dist-tag ls @micro-os-plus/micro-test-plus

Tag the npm package as latest​

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

npm dist-tag add @micro-os-plus/micro-test-plus@6.0.0 latest

Check the result:

npm dist-tag ls @micro-os-plus/micro-test-plus

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

npm deprecate @micro-os-plus/micro-test-plus@6.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 @micro-os-plus/micro-test-plus@6.0.0

Share on X/Twitter​

  • In a separate browser window, open X/Twitter
  • Using the @micro_os_plus account
  • Paste the release name such as µTest++ Testing Framework v6.0.0 released
  • Paste the link to the web page release
  • Click the Post button

Analytics​

Credits to Shields IO for the badges.

Last updated on