Skip to main content

How to make new doxygen2docusaurus releases

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

This page is for the maintainers of the Doxygen Documentation Converter project, and describes how to create 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
  • npm

To check the compatibility with the oldest supported node version, switch to it:

nvm use --lts 20
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 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 master branch is rebased onto development.

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 that Copy the master branch only is disabled.

Use the development branch, and direct the Pull Requests to the same 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 --prefix ~/Work/xpack/doxygen2docusaurus-cli-ts.git link

And in the projects that refer to 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, rebase the master branch onto the development branch
  • If necessary, rebase the website branch onto the development branch
caution

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 outdated
  • npm update or edit and npm install
  • Repeat and possibly manually edit package.json until everything is up to date
  • Commit the changes
Dependencies packages

Increase the version and update the top package.json​

The project uses SemVer, as required by npm.

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

Update CHANGELOG.md​

  • Open the CHANGELOG.md file
  • Check if all previously fixed issues are included
  • Check the latest commits with 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 * v2.2.8 prepared
  • Commit with the message prepare v2.2.8

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 with npm run git-log
  • Update CHANGELOG.md, add a line such as * v2.2.8 published on npmjs.com
  • Commit with the message CHANGELOG: publish npm v2.2.8
  • 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 2.2.8

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/blog folder: 
    npm --prefix ~/Work/xpack/doxygen2docusaurus-cli-ts.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/xpack/doxygen2docusaurus-cli-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 2.2.8 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.

Manual install test​

Test if the package can be installed globally:

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

Prepare the website​

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

  • Switch to the development branch
  • Execute the generate-website-commons npm script in the website/package.json 
    npm --prefix ~/Work/xpack/doxygen2docusaurus-cli-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/doxygen2docusaurus-cli-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/doxygen2docusaurus/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 development branch (git rebase 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 development branch (git rebase 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 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://xpack.github.io/doxygen2docusaurus/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/doxygen2docusaurus/.

Final updates​

Update the stable branch​

In this Git repository:

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

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/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@2.2.8 latest

Check the result:

npm dist-tag ls @xpack/doxygen2docusaurus

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/doxygen2docusaurus@2.2.8 "<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/doxygen2docusaurus@2.2.8

Share on X/Twitter​

  • In a separate browser window, open X/Twitter
  • Using the @xpack_project account
  • Paste the release name such as Doxygen Documentation Converter v2.2.8 released
  • Paste the link to the web page release
  • Click the Post button

Analytics​

Credits to Shields IO for the badges.

Last updated on