lthn/itns-sidechain
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
itns-sidechain/docs/release-process.md

8.6 KiB
Raw Blame History

Versioning and branching strategy

Table of Contents

This document describes the release process and branching strategy for hsd.

Release schedule and release candidates

We release up to 2 major versions of the hsd per year. We release the release candidate for the next major version one week early to allow others to join the testing of the hsd. Release candidates can be released several times until the final release date.

Versioning (Semver)

Releases can be categorized according to the semver:

  • Major release, we included backwards incompatible changes.
  • Minor release, we made backwards compatible changes.
  • Patch release, we just fixed the bugs.

This document uses following definitions for the versions:

  • latest version (major.x.x) - Last released major version where we push the minor and patch updates actively.
  • next version (major+1.x.x) - The version that will be released on the next major release date.
  • previous version (major-1.x.x).

Some useful tips for PRs:

  • Does it need database migration ? - major upgrade.
  • Does it change RPC or HTTP API in backwards incompatible way ? - major upgrade.
  • Consensus changes - major upgrade.
  • Soft fork is deployed to the latest first, if activation fails it will get removed from the next release.

Support period

We release up to 2 major version per year, but only latest 2 will be supported (latest and previous). Support types:

  • latest version (major.x.x) - active minor and patche releases.
  • previous version (major-1.x.x) - only backport critical fixes.
  • Anything prior to these is discontinued.

Changelog and release notes

CHANGELOG will only report backwards-incompatible API changes and actions users need to take to upgrade.
Each version release should be accompanied by a new release-note file for that version, which will contain detailed information of the update. This includes Pull Requests list (titles and links), CHANGELOG information related to this version.

Branching strategy

General

master branch is not associated with any released versions and should not be used in production. Each released version lives in a separate branch:

  • latest in major.x branch.
  • previous in major-1.x branch.

Minor and patch releases of these versions are released from these branches and updates are backported from the master. Merges to the released version branches must happen via Pull Requests to give other maintainers and reviewers time to review and verify what will be released.

Process below will be described as procedures for the situations:

  • release next major version candidate.
  • release next major version. (becomes latest)
  • release latest minor and patch versions.
  • release previous minor and patch versions.

Process for the latest and previous minor/patch releases is the same. At the same time only these branches should exist in the repo (Example we have just released v4.0.0):

  • master - active development.
  • v4.x - just become latest version.
  • v4.x-proposal - active backport and PR base.
  • v3.x - just become previous version.
  • v3.x-proposal - import minor/patch backport and PR base.

master branch and package.json version

master branch only accumulates changes from PRs and is mostly untested(other than PR testing). next release candidate will branch off from the master. Package version in the master branch will always be set to the latest but will have minor version set to 99 to signify the unsafe version (latestMajor.99.0).

Release candidate and major release

master branch already contains everything that needs to be released with the next version. Instead of directly creating branch to the next version, we create branch-proposal to allow brief review of the contents of the release. The purpose of proposal branches is to allow other maintainers and reviewers to suggest including something else. Proposal should not get dragged out and take max 2-3 days before moving on. At this point we don't want to add more complex things to the release candidate, only patches until release(feature lock).

Process example (e.g. latest was 3.1.0 and we are releasing 4.0.0-rc.1):

  • Update network seeds.
  • Add a new checkpoint which should be ~4-6 months before the release.
  • update package.json version to 4.99.0 in master branch.
  • update package-lock.json by running npm install.
  • create branch 4.x from the master.
  • create branch 4.x-proposal from the master.
  • update package.json version to 4.0.0-rc.1 in 4.x-proposal branch.
  • update package-lock.json by running npm install.
  • optional: In case we want to omit some changes from the master, you can also rebase and discard those commits.
  • Create Release doc docs/release-notes/release-notes-4.x.md.
  • Update CHANGELOG file with the incompatibilities and actions to take.
  • Create PR: Release v4.0.0-rc.1 from branch 4.x-proposal to 4.x.
    • PR description containing list of PRs (similar to release notes)
    • We can discuss if we want to add something the release candidate for testing.

After discussion and review (this should be relatively quick) of the proposal we do the release of the release candidate:

  • Merge proposal PR to the 4.x branch.
  • Create the release files for the 4.0.0-rc.1.

Next release candidate

After release-candidate is released, we can use next.x-proposal branch to accumulate backports for the patches that are found during testing period.

Process example:

  • backport patch(es) from the master to the 4.x-proposal.
  • update package.json version to 4.0.0-rc.2 in the 4.x-proposal.
  • update package-lock.json by running npm install.
  • Update Release doc file for the docs/release-notes/release-notes-4.x.md.
  • Update CHANGELOG file with the incompatibilities and actions to take. (should not be any)
  • Create PR Release v4.0.0-rc.2 from branch 4.x-proposal to 4.x.
    • PR lists new PRs that are being added.
  • Quick review and merge
  • Create the release files for the 4.0.0-rc.2.
  • Next release candidate does not need to update main version tags. (see release below)

Release the major version

Above process continues until last week where we do the actual release:

  • update package.json version to 4.0.0 in the 4.x-proposal branch.
  • update package-lock.json by running npm install.
  • CHANGELOG should be up to date.
  • Create PR Release v4.0.0 from the branch 4.x-proposal to 4.x.
    • PR list from prev PRs.
  • Final review before release
  • Release files for the 4.0.0
  • Update latest tag.
  • Update previous tag.
  • Backport release notes to master.

Release minor and patches

This applies to all minor and patches that are being backported to the latest, previous versions. Example v4.0.0 is latest and we want to release minor(process is the same for previous minor and patch releases):

  • Update package.json version to 4.1.0 in the 4.x-proposal branch.
  • Update package-lock.json by running npm install.
  • Update Release doc file docs/release-notes/release-notes-4.x.md.
  • NO CHANGES TO CHANGELOG - this is minor.
  • Create PR Release v4.1.0 from the branch 4.x-proposal to 4.x.
    • PR description containing list of PRs (similar to release notes)
    • We can discuss if we want to add something the release candidate for testing.
  • Review and merge.
  • Tag v4.1.0 from the 4.x.
  • Release files for the 4.1.0.
  • Depending on the version we are upgrading, update relevant tag:
    • latest if we are releasing from the last major.
    • previous if we are updating previous versions minor.
  • Backport release notes to master.