Skip to main content

How to make new doxygen2docusaurus releases

GitHub package.json version NPM Version GitHub issues GitHub pulls TypeScript ESLint licence

This page is designed for maintainers of the Doxygen Documentation Converter project and provides documentation on creating new releases.

Prerequisites​

@xpack/doxygen2docusaurus is a portable Node.js project; 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.0
  • npm

To ensure compatibility with older node versions, it is preferable to revert to an older one:

nvm use --lts 20
code

Obtain project sources​

The project is hosted on GitHub:

Branches

This project utilises 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
  • webpreview, containing the current preview website content; pushes to this branch automatically trigger publication of the preview 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 development branch is merged into master.

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

rm -rf ~/Work/xpack/doxygen2docusaurus-cli-ts.git && \
mkdir -p ~/Work/xpack && \
git clone \
  --branch master \
  https://github.com/xpack/doxygen2docusaurus-cli-ts.git \
  ~/Work/xpack/doxygen2docusaurus-cli-ts.git
For development purposes, clone the development branch.
rm -rf ~/Work/xpack/doxygen2docusaurus-cli-ts.git && \
mkdir -p ~/Work/xpack && \
git clone \
  --branch development \
  https://github.com/xpack/doxygen2docusaurus-cli-ts.git \
  ~/Work/xpack/doxygen2docusaurus-cli-ts.git

Alternatively, if the repository has already been cloned:

git -C ~/Work/xpack/doxygen2docusaurus-cli-ts.git pull
tip

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

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

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

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

npm link -C ~/Work/xpack/doxygen2docusaurus-cli-ts.git

And in the projects referring it:

npm link @xpack/doxygen2docusaurus

Release schedule​

There are no fixed releases.

Prepare a new release​

Check Git​

In the xpack/doxygen2docusaurus-cli-ts Git repository:

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

This is critically important; otherwise you will release the previous content again!

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

Update npm packages​

note

This package is also utilised by the VS Code extension and, until VS Code accepts ESM dependencies, it must be maintained as a legacy CommonJS dependency.

  • 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

Maintain:

  • @types/node locked to the latest version that still matches the oldest supported node (20).
Dependencies packages

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 1.1.0)
  • Update the version in the top package.json file
  • Use the new version, suffixed by -pre, such as 1.1.0-pre.

Update the websiteConfig (if necessary)​

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

Update the website commons​

Execute the generate-website-commons npm script from website/package.json within the project folder.

npm run generate-website-commons -C website

Start the local web server​

Execute the npm script clean followed by start in the website sub-project, or execute the following within 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 resolve them; assign them to a milestone (such as 1.1.0).

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

Set the new version​

Execute the following within the project folder:

npm version 1.1.0

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

CI tests​

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 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; utilise the following syntax 
    - [[#N](https://github.com/xpack/doxygen2docusaurus-cli-ts/issues/N)]:
  • Commit with the message website: blog post release 1.1.0 published

Publish the release to npmjs.com​

Execute the following command within the project folder:

npm publish --tag next
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.

Manual install test​

Test if the package can be installed globally:

npm install --location=global @xpack/doxygen2docusaurus@next

Validate the website content through a local build using the npm build script:

npm run build

Prepare the website​

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

  • Switch to the development branch
  • Execute 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 by performing a local build using the npm build script:

npm run build -C website

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://xpack.github.io/doxygen2docusaurus/.

Final updates​

Update the stable branch​

In this Git repository:

  • Select the master branch
  • Merge the development branch into the master branch
  • Push the master branch to GitHub
  • Check out the development branch
note

Avoid further updates to the master 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/xpack/doxygen2docusaurus-cli-ts/milestones:

  • Close the current milestone.

Check npm package tags​

Execute the following command in a terminal:

npm dist-tag ls @xpack/doxygen2docusaurus

Tag the npm package as latest​

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

npm dist-tag add @xpack/doxygen2docusaurus@1.1.0 latest

Check the result:

npm dist-tag ls @xpack/doxygen2docusaurus

Should the release prove problematic and require unpublishing:

npm unpublish @xpack/doxygen2docusaurus@1.1.0

Analytics​

Credits to Shields IO for the badges.