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 license

This page is designed for maintainers of the µTest++ Testing Framework project and provides documentation on 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 carried out 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 run the native tests with the system tools, a C++ development environment is required. On macOS install Command Line Tools, on Ubuntu build-essential.

For details on installing the prerequisites, please read the Prerequisites page.

Get project sources​

The project is hosted on GitHub:

Branches

The project uses multiple branches:

  • master, not actively used
  • xpack, with the latest stable version (default)
  • xpack-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

All development is done 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 merged into xpack.

To clone the stable branch (xpack), run 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

Or, if the repo was already cloned:

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

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

Use the xpack-development branch and be sure you contribute the Pull Requests back to the xpack-development branch.

During development, it is convenient to have a writable instance of the library to make 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
Get the writable helper sources (optional, for development purposes)

The project has a dependency to a common helper, that is normally installed as a read-only dependency; for development purposes, to be able to make changes to the scripts located inside 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

Or, if the repo was already cloned:

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

If a writable instance of this library is needed 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​

As formatting style, the library uses a .clang-format configuration file based on the GNU style.

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

info

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

tip

Always reformat the source files that were changed 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 repo:

  • switch to the xpack-development branch
  • pull new changes
  • if necessary, merge the xpack branch
  • if necessary, merge the website branch
caution

This is really important, otherwise you will release the previous content again!

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

Increase the version and update the top package.json​

As required by npm modules, this one also uses SemVer.

  • determine the next version (like 3.2.2)
  • update the version in the top package.json file
  • use the new version, suffixed by -pre, like 3.2.2-pre.

Update the websiteConfig (if necessary)​

Check and possibly update the release specific properties (if any) in website/package.json.

Update the website commons​

Run the generate-website-commons npm script from website/package.json in the project folder.

npm run generate-website-commons -C website

Start the local web server​

Execute the npm script clean then start in the website sub-project, or run the following in the project folder:

npm run clean -C website
npm run start -C website

Navigate to the Maintainer Info page, the Start the local web server section.

Fix possible open issues​

Check GitHub Issues and Pull Requests:

and fix them; assign them to a milestone (like 3.2.2).

Update CHANGELOG.md​

  • open the CHANGELOG.md file
  • check if all previous fixed issues are in
  • check the latest commits npm 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 * v3.2.2 prepared
  • commit with the message prepare v3.2.2

Reformat source files​

  • reformat the source files that were changed
  • commit and push

Manual tests​

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

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

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

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

To run 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 run 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 run 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 run 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​

Running all tests may require several gigabytes of space.

To clean up the tests folder, use:

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

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

xpm clean-ups

For a thorough clean-up, please note that xpm uses only two folders:

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

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

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 into the xpack-development branch
  • check the latest commits npm run git-log
  • update CHANGELOG.md, add a line like * v3.2.2 published on npmjs.com
  • commit with the message CHANGELOG: publish npm v3.2.2
  • check the list of files included in the npm package: 
    npm run pack
  • possibly update .npmignore

Set the new version​

Run the following in the project folder:

npm version 3.2.2

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, that runs 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
  • run the generate-website-blog-post npm script; this will add a file in the website/blog folder: 
    npm run generate-website-blog-post -C website
  • edit the front matter properties (the description property)
  • select the correct summary (maintenance vs. new release)
  • add entries in the Bug fixes; use 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.2.2 published

Publish the release to npmjs.com​

Run the following command in the project folder:

npm publish --tag next
tip

When publishing for the first time, use --access public.

After a few moments the version will be visible at npmjs.com, the Versions tab.

Publish the website​

Re-generate the Doxygen pages​

Run the doxygen npm script:

npm run doxygen -C website

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

With the current configuration, the static html pages are generated in the website/static/reference folder.

Prepare the website​

The documentation site is built with Docusaurus and published in the project GitHub Pages.

  • switch to the xpack-development branch
  • run the website-generate-commons npm script in the website/package.json 
    npm run website-generate-commons -C website
  • commit all changes

Build the static website locally​

Validate the website content in a local build via the npm build script:

npm run build -C website

Fix any broken links, if any.

Publish the website​

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

The website branch may be subsequently updated, as long as the version in package.json is not changed.

Check the result at https://micro-os-plus.github.io/micro-test-plus-xpack/.

Final updates​

Update the stable branch​

In this Git repo:

  • select the xpack branch
  • merge the xpack-development branch into the xpack branch
  • push the xpack branch to GitHub
  • checkout 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 were addressed.

Close milestone​

In https://github.com/micro-os-plus/micro-test-plus-xpack/milestones:

  • close the current milestone.

Check npm package tags​

Run 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.2.2 latest

Check the result:

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

In case the release proves problematic and needs to be unpublished:

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

Analytics​

Credit to Shields IO for the badges.

TODO​

  • Possibly split the content into separate classes.