diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..a076af8a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,15 @@ +HSD +=== + +## Links + - [Installation](./hsd#install) + - [Release process](./release-process.md) + - [Release files](./release-files.md) + - [Release schedule](./release-schedule.md) + +## External Links + - [Documentation repository](https://github.com/handshake-org/handshake-org.github.io) + - [Guides](https://hsd-dev.org) + - [API Doc](https://hsd-dev.org/api-docs/) + - [Code generated docs](https://hsd-dev.org/hsd) + - [Paper](https://hsd-dev.org/files/handshake.txt) diff --git a/docs/release-files.md b/docs/release-files.md new file mode 100644 index 00000000..5b83aad0 --- /dev/null +++ b/docs/release-files.md @@ -0,0 +1,5 @@ +Releasing hsd +============= + +This document contains information about bundling, signing and +distributing the files. diff --git a/docs/release-process.md b/docs/release-process.md new file mode 100644 index 00000000..d3e40cfb --- /dev/null +++ b/docs/release-process.md @@ -0,0 +1,178 @@ +# Versioning and branching strategy + +## Table of Contents + * [Release schedule and release candidates](#release-schedule-and-release-candidates) + * [Versioning (Semver)](#versioning-semver) + * [Support period](#support-period) + * [Changelog and release notes](#changelog-and-release-notes) + * [Branching strategy](#branching-strategy) + + [General](#general) + + [master branch and package.json version](#master-branch-and-packagejson-version) + + [Release candidate and major release](#release-candidate-and-major-release) + - [Next release candidate](#next-release-candidate) + - [Release the major version](#release-the-major-version) + + [Release minor and patches](#release-minor-and-patches) + +This document describes the release process and branching strategy +for the handshake. + +## Release schedule and release candidates + We release 2 major versions of the hsd per year (October and April). We +release the `release candidate` for the next major version, month 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 release date. + - `previous` version (`major-1.x.x`). + - `life-support` version (`major-2.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. (Even if it's a soft fork) + +## Support period + We release 2 major version per year and we want to support each version at +least for a year. This means that we will support 2 more versions on top of the +`latest` version. For example current version `3.x.x` will get at least security +fixes, until version `6.x.x` is released. Support types: + - `latest` version (`major.x.x`) - active minor and patche releases. + - `previous` version (`major-1.x.x`) - backport patches and minor fixes + only if it improves performance or has high impact. + - `life-support` version (`major-2.x.x`)- only backport security fixes. + - Anything prior to these is discontinued. + +NOTE: We should also collect stats for the active node versions in the network. + +## Changelog and release notes + CHANGELOG will only create backwards incompatible API change notes and +actions users need to take to upgrade. + Each version should create new release-note for the version, that will +contained 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. + - `life-support` in `major-2.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 procedurs 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. + - release `life-support` 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 developmeny + - `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. + - `v2.x` - just become `life-support` version. + - `v2` does not have proposal, because it only supports critical fixes, which + wont go through standard PR release process. + +### 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 `next` but +will have `patch` version set to `99` to signify the unsafe version +(`latestMajor+1.0.99`). + +### 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 `patch`es until release(feature lock). + +Process example (e.g. `latest` was `3.1.0` and we are releasing `4.0.0-rc.1`): + - create branch `4.x-proposal` from the `master` + - update `package.json` version to `5.0.99` in `master` branch. + - update `package.json` version to `4.0.0-rc.1` in `4.x-proposal` branch. + - optional: In case we want to omit some changes from the `master`, + you can also rebase and discard those commits. + - Create Release doc file for the + `docs/release-notes/release-notes-4.0.0-draft.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][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 `backport`s for the `patch`es 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 Release doc file for the + `docs/release-notes/release-notes-4.0.0-draft.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][release-files] for the `4.0.0-rc.2`. + +#### 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. + - Rename relase doc file from + `docs/release-notes/release-notes-4.0.0-draft.md` to + `docs/release-notes/release-notes-4.0.0.md` + - 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][release-files] for the `4.0.0` + - Update [schedule][schedule] if necessary + +### 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. + - Create Release doc file `docs/release-notes/release-notes-4.1.0.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][release-files] for the `4.1.0`. + +[release-files]: ./release-files.md +[schedule]: ./release-schedule.md diff --git a/docs/release-schedule.md b/docs/release-schedule.md new file mode 100644 index 00000000..1fae63c4 --- /dev/null +++ b/docs/release-schedule.md @@ -0,0 +1,9 @@ +Maintenance period +================== + +| Version | Release Date | Maintenance End | End of Life | +| ------- | ------------ | --------------- | ----------- | +| v3.x | 2021-10-14 | 2022-10-01 | 2023-04-01 | +| v4.x | 2022-04-30 | 2022-04-01 | 2023-10-01 | +| v5.x | 2022-10-31 | 2022-10-01 | 2024-04-01 | +| v6.x | 2023-04-30 | after v8.0 | after v9.0 | diff --git a/lib/pkg.js b/lib/pkg.js index 1df8ff44..dc4ad31a 100644 --- a/lib/pkg.js +++ b/lib/pkg.js @@ -70,7 +70,7 @@ pkg.cfg = `${pkg.core}.conf`; * @default */ -pkg.version = '3.0.1'; +pkg.version = require('../package.json').version; /** * Repository URL.