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 designed for maintainers of the µTest++ Testing Framework project and provides documentation on creating 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 (although some npm scripts must be executed within a Git Bash terminal).

The prerequisites are:

  • git
  • node >= 20.0
  • 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 utilises 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-development branch is rebased onto xpack.

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

rm -rf ~/Work/micro-os-plus/micro-test-plus-xpack.git && \
mkdir -p ~/Work/micro-os-plus && \
git clone \
  --branch xpack \
  https://github.com/micro-os-plus/micro-test-plus-xpack.git \
  ~/Work/micro-os-plus/micro-test-plus-xpack.git
For development purposes, clone the xpack-development branch.
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

Alternatively, if the repository has already been cloned:

git -C ~/Work/micro-os-plus/micro-test-plus-xpack.git pull
tip

To contribute Pull Requests, fork the project and ensure the Copy the master branch only is disabled.

Utilise the xpack-development branch and ensure you contribute the Pull Requests back to the xpack-development branch.

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

To facilitate the use of a writable instance of this library in other projects, add a link from the user's global xPacks store to this local development folder:

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

And in the projects referring 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 user's global xPacks store:

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

If a writable instance of this library is required in another project, add a link from the user's global xPacks store to it:

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

Code formatting​

For formatting style, the library employs a .clang-format configuration file based on the GNU style.

Code formatting is performed using clang-format --style=file, either manually via a script, or automatically through Visual Studio Code, or the Eclipse CppStyle plug-in.

info

Visual Studio Code can directly utilise the .clang-format file within the Format Document command.

tip

Always reformat the source files that have been modified before committing them to the repository.

Release schedule​

There are no fixed releases.

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
  • If necessary, rebase the website branch
caution

This is critically important; otherwise you will release the previous content 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​

As required by npm projects, this one also utilises SemVer.

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

Update the websiteConfig (if necessary)​

Check and possibly update the release-specific properties (like the version and release date) within website/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 Info page, the Start the local web server section.

Fix possible open issues​

Check GitHub Issues and Pull Requests:

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

Update CHANGELOG.md​

  • Open the CHANGELOG.md file
  • Check if all previously fixed issues are included
  • Check the latest commits npm run git-log; if necessary, copy/paste lines, group by dates and edit them using the regular expressions below
  • To convert 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 remaining dates, change from: 
    ^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] [*]
    to: 
    *
  • Add a new entry such as * v3.3.1 prepared
  • Commit with the message prepare v3.3.1

Reformat source files​

  • Reformat the source files that were changed
  • Commit and push

Manual tests​

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

It is recommended to commence by performing some clean-ups (not necessary following the initial git clone):

npm --prefix ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests install
xpm run deep-clean -C ~/Work/micro-os-plus/micro-test-plus-xpack.git/tests
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

Clean-ups​

Executing all tests may require several gigabytes of space.

To clean up the tests folder, utilise:

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

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

xpm clean-ups

For a comprehensive clean-up, please note that xpm utilises only two folders:

  • %APPDATA%\Roaming\xPacks
  • %APPDATA%\Local\Caches\xPacks

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

However, projects linking to the user's global xPacks store will fail with broken paths.

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 npm run git-log
  • Update CHANGELOG.md, add a line such as * v3.3.1 published on npmjs.com
  • Commit with the message CHANGELOG: publish npm v3.3.1
  • Check the list of files included in the npm package: 
    npm run npm-pack
  • Possibly update .npmignore

Set the new version​

Execute the following within the project folder:

npm version 3.3.1

The postversion npm script should also update tags via git push origin --tags; this should also trigger CI tests.

CI tests​

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)
  • Add entries in the Bug fixes; utilise the following syntax 
    - [[#N](https://github.com/micro-os-plus/micro-test-plus-xpack/issues/N)]:
  • Commit with the message website: blog post release 3.3.1 published

Publish the release to npmjs.com​

Login to npmjs.com:

npm login

Execute the following command within the project folder:

npm publish --tag test
tip

When publishing for the first time, utilise --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 doxygen npm script:

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

At present, the doxygen programme 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.

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 website-generate-commons npm script in the website/package.json 
    npm --prefix ~/Work/micro-os-plus/micro-test-plus-xpack.git/website run website-generate-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, utilising a dedicated workflow in GitHub Actions.

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-development branch onto the xpack branch
  • 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 possible 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@3.3.1 latest

Check the result:

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

Should the release prove problematic and require unpublishing:

npm unpublish @micro-os-plus/micro-test-plus@3.3.1

Analytics​

Credits to Shields IO for the badges.

TODO​

  • Possibly split the content into separate classes.