Skip to content

Latest commit

 

History

History
259 lines (209 loc) · 6.3 KB

MAINTAINING.adoc

File metadata and controls

259 lines (209 loc) · 6.3 KB
Raw

A Maintainers' Guide

Table of Contents

Semantic Versioning

We must follow Semantic Versioning rules when publishing packages, and especially:

  • Never publish breaking changes, including regarding tooling and installation, between two versions of the same MAJOR.

  • Keep the semantics right between MINOR and PATCHES. MINORs convey new features while patches convey fixes.

If you have a doubt, read the Semantic Versioning standard, v2.0 at semver.org. It’s not that long.

Branching

Development branches

The branching system is highly coupled with Semantic Versioning. We support backporting fixes to different MAJOR versions. To do so, we adopt the following conventions:

  • master is the ultimate development branch for the upmost MAJOR, accepting PRs, fixes, new features…​ etc.

  • Any development branch for a MAJOR strictly inferior to master’s MAJOR will have a name composed with the following pattern:

    dev/MAJOR.x

These development branches will be used to cherry-pick backports from master.

Release branches

ℹ️
 Release branches target a MAJOR.MINOR release. Patches within this minor will get merged. This is especially useful to hold references to documentation for a specific release while accounting for the fact it can be a moving target.

Release branches have a name composed with the following pattern:

release/MAJOR.MINOR

Transient branches

⚠️
 Transient branches should never be worked on by more than one person at a time, unless authors are completely aware of their collaboration.
ℹ️
 Transient branches should be based on master and rebased before merging to master. They should be deleted after merged to master.

These branches are meant for short-term development cycles such as pull requests. These branches' names should follow the following pattern:

PREFIX/QUALIFIER
PREFIX Description QUALIFIER Examples

feat

New features

The issue number this feat will cover, or a slug summarizing the feature

feat/001
feat/inline-css

fix

Bug fixes

The issue number this fix will address, or a slug summarizing this fix.

fix/001
fix/start-attribute

reg

(Anti) regression tests

The issue number this test will reproduce.

reg/001

tests

Coverage or other tests

A slug summarizing the areas covered by the test(s).

tests/image-renderer

rfc

Requests For Comments

A slug summarizing the area covered by the RFC.

rfc/whitespaces

opt

Optimizations

The issue number this optimization will address, or a slug summarizing the optimization.

opt/103
opt/rendering-cycles

Publishing

🔥
 Pre-releases should be prepared from master or dev/MINOR.x (cf, Branching).

The publishing cycle entails pre-releases, which are usually tagged on npm with next. The table below describes the relationship between releases names, npm tags and their semantics. Custom npm tags can also be used to denote a new MAJOR version in early-stage development.

Release type Npm tag Version suffix Description

Unstable

unstable

-alpha.x

Features and API can evolve.

Frozen

next

-beta.x

Features are frozen. Eventually, new fixes and optimizations can be merged.

Stable

latest
release/MAJOR.MINOR

none

Stable releases.

Pre-releases

Prerequisites

  • ❏ Tests are passing;

  • ❏ I’m on the master (or a dev/MINOR.x branch if I’m backporting fixes);

  • ❏ If the release is frozen, I’ve updated the changelog with a next entry;

  • ❏ I have changed the version in package.json;

  • ❏ I have commited my changes;

  • ❏ I have tagged this very commit with v<semver>, replacing <semver> with the version in package.json.

Steps

We use release-it utility to release new versions. You will need to provide a GIHUB_TOKEN environment variable to publish the release on Github.

  1. Run

    yarn render-html release-it --preRelease=beta --npm.tag=next

    for a beta or

    yarn render-html release-it --preRelease=alpha --npm.tag=unstable

    for an alpha release. Eventually, edit manually the CHANGELOG.md file to add extra information.

  2. If this is the first pre-release, create a new issue on Github to be pinned, asking for feedback for this pre-release. This issue must have the release label.

  3. Release the new documentation website with

    yarn publish:website

    You will need to pass a USER environment variable to this command if your github user has a different name than your logged system user.

  4. Release the new discovery app with

    yarn publish:discovery

Releases

Prerequisites

  • ❏ Tests are passing;

  • ❏ I’m on the master (or a dev/MINOR.x branch if I’m backporting fixes);

  • ❏ I’ve updated the changelog with a <version> entry;

  • ❏ I have changed the version in package.json;

  • ❏ I have commited my changes;

  • ❏ I have tagged this very commit with v<semver>, replacing <semver> with the version in package.json.

Steps

We use release-it utility to release new versions. You will need to provide a GIHUB_TOKEN environment variable to publish the release on Github.

  1. Run

    yarn render-html release-it

    Eventually, edit manually the CHANGELOG.md file to add extra information.

  2. Release the new documentation website with

    yarn publish:website

    You will need to pass a USER environment variable to this command if your github user has a different name than your logged system user.

  3. Release the new discovery app with

    yarn publish:discovery

If this publication was a backport (from a dev/MINOR.x branch), you must cherry-pick the version commit into master.

  1. Checkout and pull master

    git switch master
git pull

  2. Cherry-pick the commit you have previously made on dev/MINOR.x branch.

    git cherry-pick <commit-id>

    If you must resolve conflicts, make sure:

    • ❏ The new changelog entry is positionned in the approriate order;

    • ❏ The package.json version remains the upmost.