Releasing documentation

Coming soon

This page needs to be rewritten for writers

Releasing code libraries is the first step of the Vertical release process described in the Version management principles page.

Making good releases

Releasing is a critical step in the lifecycle of your facet. As a repository owner, you're in charge of delivering predictable and reliable updates:

• predictable: the list of changes is clearly documented so that your consumers know what to expect from it (new features, bug fixes, breaking changes).
• reliable: the update is actually doing what it pretends, not bringing unexpected changes or side effects.

To help with this, on top of writing good code, we use the semantic-release tool in our CI to automate the release,.

Where packages are published

Packages are published to several registries depending on the license they use in their package.json file. The following table shows in which registries the packages are published for each license used in Quartz:

License	Public NPM registry	Quartz's private GitHub Packages	Schneider Electric internal registry
Private	❌	✅	✅
Apache 2.0	✅	✅	✅
Creative Commons 4.0	✅	✅	✅

This logic is included in the Quartz's semantic-release preset (see further).

All packages are released under the @quartzds scope

All registries use the @quartzds scope to host the Quartz packages. See the Naming conventions page for detailed naming rules.

How semantic-release works

semantic-release uses the commit messages to determine the consumer impact of changes in the codebase. Following formalized conventions for commit messages, semantic-release automatically determines the next semantic version number, generates a changelog and publishes the release.

— Excerpt from the semantic-release documentation

The workflows in GitHub Actions are configured to execute the following jobs:

1. Run the linting, testing and build steps
2. Run semantic-release in --dry-mode to check the release will go fine without actually pushing packages into the wild
3. Run semantic-release (only on the next and main branches) to:
   • compute and update the version number in your package.json file
   • generate and update the release notes in the CHANGELOG.mdfile
   • publish the packages with the next or latest npm tag on the appropriate registries

Quartz preset for semantic-release

To ease and standardize the automated releases, Quartz provides a semantic-release preset. This preset is included in your package.json and provides the specific rules and configurations for Quartz:

• the commit types, as described in the Conventional commits section of the Versioning page
• the target registries based on the license declared in the license field of the package.json file
• the numbering rules (including the -beta.X suffix)
• which npm tag to apply depending on the branch
• and other configuration details

About npm tags

npm tags can be used to provide an alias instead of version numbers.

A tag can be used when installing packages as a reference to a version instead of using a specific version number:

npm install @quartzds/<name>@<tag>`

By default, the latest tag is used by npm to identify the current version of a package, and npm install <pkg> (without any @<version> or @<tag> specifier) installs the latest tag.

Quartz uses the following tags:

• next: the latest beta release of a package
• latest: the latest production release of a package

Release lifecycle

Follow these steps to ensure a good developer experience to your consumers when they will update your packages:

1. Release a beta version
2. Collect feedback from early testers
3. Make any necessary fixes and release a new beta version
4. When stable, release a production version
5. Continue the vertical release process

Note

Although understanding the Quartz code release process is interesting to all developers, this page is primarily targeted at repository owners.

Release a beta version

As explained in the Versioning page, contributed Pull Requests (PRs) should first be merged into the next branch.

To do

Elaborate

Collect feedback from early testers

Once this beta release is done, you should notify your consumers (reporters of a bug, pilot projects for new features) and ask them to test the update.

This beta stage is precious to improve production release quality

Don't overlook beta releases. Requesting early feedback will help you catch issues you may have missed despite your best efforts during development.

Your production releases will be more reliable and predictable.

Release a production version

Once the preview packages on the next branch have been tested and validated, you can merge the next branch into the main branch.

Only the repository owners are allowed to push to the next and main branches. Because you checked the quality of the contribution in the beta stage, you don't need to create a Pull Request for that merge.

How often to release production versions

The scope and frequency of production releases is up to your team. We recommend releasing often; that's why we automated the process using semantic-release.

To do

Review the "you don't need to create a Pull Request for merging into main" assumption with dev leads

The CI workflow is going through the same steps as the beta stage, with the following differences:

• it creates a production version (following the Semantic versioning rules)
• it publishes the package with the latest npm tag.

Announce the release

To do

• Who/where to announce
• Announcement template

An example release history

The following Git diagram shows an example release history using semantic-release with the custom Quartz preset:

You can see typical release and versioning scenarios:

1. The feat/123-foo-syntax branch is adding a new feature, so the next version would be 1.1.0

   • As it is merged into the next branch, a 1.1.0-beta.1 beta version is released.
   • Then, the next branch is merged into main, which releases the 1.1.0 production version.

2. The fix/456-bar-syntax-bug branch is fixing a bug, so the next version would be 1.1.1.

   • As it is merged into the next branch, a 1.1.0-beta.1 beta version is released.
   • Then, the next branch is merged into main, which releases the 1.1.1 production version.

3. Finally, the feat/789-button-tooltip branch is adding a new feature, but it is also introducing breaking changes (as depicted by the exclamation mark ! near the commit type), so the next version would be 2.0.0.

   • As it is merged into the next branch, a 2.0.0-beta.1 beta version is released.
   • Then, the next branch is merged into main, which releases the 2.0.0 production version.