Skip to main content

Release how-to

This page explains the steps needed to release a new version of maxgraph@core.

Currently, the release process is completely manual. Automation will come later based on the information provided here.

Prerequisites​

  • Releases are done from the default branch
  • Ensure that all GitHub Actions runs are successful
  • Make sure that the documentation is up-to-date

Preparation​

Decide on the new version depending on the type of changes:

  • Follow semver
  • Check the new commits since the latest release to determine the type of changes included in the new version.
  • Until we release the first major version, bump the minor version if the release contains new features or breaking changes.

Check the milestone associated with the new release. Note: We always put issues related to a version into a Milestone whose name matches the version.

  • Make sure that the name of the milestone used for the new release version matches the name of the version being released. Rename it if necessary.
  • Verify that all issues related to the upcoming release are attached to the milestone. In particular, check the issues that do not have a milestone.
  • Clean up this open milestone if some issues are still open (move them to a new milestone or discard the milestone from them).
  • Close the milestone.

Apply changes in the source code

  • Prerequisites:
    • Releases are done from the default branch, so all changes are done in the main branch.
    • These changes are going to be done locally, and then pushed to the repository.
    • Make sure that the code is up-to-date with the main branch. Run git pull to get the latest changes.
  • Update the version in packages/core/package.json and the VERSION constant in the packages/core/src/Client.ts file.
  • Update the package-lock.json file by running npm install at the root of the repository. It should only change the version of @maxgraph/core.
  • Update the CHANGELOG file to list the major changes included in the new version. Be generic and add a link to the future GitHub release that will contain detailed release notes, as shown below.
For more details, see the [0.1.0 Changelog](https://github.com/maxGraph/maxGraph/releases/tag/v0.1.0) on
the GitHub release page.

  • Make a single commit that includes the changes described above

    • Use the following template for the commit message: chore(release): prepare version 0.2.0

  • Push the changes

    • The default branch is protected by a GitHub ruleset that prevents direct pushing to the branch.
    • Update the ruleset and add a bypass permission for your account.
    • Run the git push command.
    • Update the ruleset to remove the bypass permission.

  • Create a git annotated tag, prefixing the version with a v. For example, if the version is 0.2.0, run:

git fetch --tags
git tag -a v0.2.0 -m "chore: release version 0.2.0"
  • Push the tag
    • As for the default branch, tags are protected by a GitHub ruleset that prevents direct pushing tags.
    • Update the ruleset and add a bypass permission for your account.
    • Run the git tag push, for example git push origin v0.2.0
    • Update the ruleset to remove the bypass permission.

Publish the npm package​

The package is published automatically once the Git tag is pushed thanks to a GitHub workflow.

If its execution fails, and you want to publish the package manually:

  • Checkout the tag that has just been created
  • From packages/core:
    • run npm publish

Create the GitHub release​

The release workflow has initiated a new draft GitHub release, which needs to be updated and published. For more details about GitHub release, follow the GitHub help

This new draft release includes a template to guide the writing of the content, so update the content accordingly to the changes included in the new version.

The list of the major changes has been automatically generated. Review and adjust it if necessary:

  • It is based on the labels of the merged Pull Requests included in this release and the GitHub release configuration.
  • If the list is incorrect (for example, an item is not in the correct category), update the label(s) or the associated Pull Request and regenerate the list.

Attach the examples and the website to the release (in the "assets" location):

Before you publish the release, make sure that a discussion will be created in the Announces category when the release is published.

Publish the release.

Review the newly created discussion in the Announces category: