Skip to content

Commit e7771b6

Browse files
nodechnodech
committed
docs: Add release process.
1 parent e8c9632 commit e7771b6

File tree

5 files changed

+208
-1
lines changed

5 files changed

+208
-1
lines changed

‎docs/README.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
HSD
2+
===
3+
4+
## Links
5+
- [Installation](./hsd#install)
6+
- [Release process](./release-process.md)
7+
- [Release files](./release-files.md)
8+
- [Release schedule](./release-schedule.md)
9+
10+
## External Links
11+
- [Documentation repository](https://github.com/handshake-org/handshake-org.github.io)
12+
- [Guides](https://hsd-dev.org)
13+
- [API Doc](https://hsd-dev.org/api-docs/)
14+
- [Code generated docs](https://hsd-dev.org/hsd)
15+
- [Paper](https://hsd-dev.org/files/handshake.txt)

‎docs/release-files.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Releasing hsd
2+
=============
3+
4+
This document contains information about bundling, signing and
5+
distributing the files.

‎docs/release-process.md

+178
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Versioning and branching strategy
2+
3+
## Table of Contents
4+
* [Release schedule and release candidates](#release-schedule-and-release-candidates)
5+
* [Versioning (Semver)](#versioning-semver)
6+
* [Support period](#support-period)
7+
* [Changelog and release notes](#changelog-and-release-notes)
8+
* [Branching strategy](#branching-strategy)
9+
+ [General](#general)
10+
+ [master branch and package.json version](#master-branch-and-packagejson-version)
11+
+ [Release candidate and major release](#release-candidate-and-major-release)
12+
- [Next release candidate](#next-release-candidate)
13+
- [Release the major version](#release-the-major-version)
14+
+ [Release minor and patches](#release-minor-and-patches)
15+
16+
This document describes the release process and branching strategy
17+
for the handshake.
18+
19+
## Release schedule and release candidates
20+
We release 2 major versions of the hsd per year (October and April). We
21+
release the `release candidate` for the next major version, month early to
22+
allow others to join the testing of the `hsd`. `Release candidates` can be
23+
released several times until the final release date.
24+
25+
## Versioning (Semver)
26+
Releases can be categorized according to the semver:
27+
- Major release, we included backwards incompatible changes.
28+
- Minor release, we made backwards compatible changes.
29+
- Patch release, we just fixed the bugs.
30+
31+
This document uses following definitions for the versions:
32+
- `latest` version (`major.x.x`) - Last released major version where
33+
we push the minor and patch updates actively.
34+
- `next` version (`major+1.x.x`) - The version that will be released
35+
on the next release date.
36+
- `previous` version (`major-1.x.x`).
37+
- `life-support` version (`major-2.x.x`).
38+
39+
Some useful tips for PRs:
40+
- Does it need database migration ? - major upgrade.
41+
- Does it change RPC or HTTP API in backwards incompatible way ? - major
42+
upgrade.
43+
- Consensus changes - major upgrade. (Even if it's a soft fork)
44+
45+
## Support period
46+
We release 2 major version per year and we want to support each version at
47+
least for a year. This means that we will support 2 more versions on top of the
48+
`latest` version. For example current version `3.x.x` will get at least security
49+
fixes, until version `6.x.x` is released. Support types:
50+
- `latest` version (`major.x.x`) - active minor and patche releases.
51+
- `previous` version (`major-1.x.x`) - backport patches and minor fixes
52+
only if it improves performance or has high impact.
53+
- `life-support` version (`major-2.x.x`)- only backport security fixes.
54+
- Anything prior to these is discontinued.
55+
56+
NOTE: We should also collect stats for the active node versions in the network.
57+
58+
## Changelog and release notes
59+
CHANGELOG will only create backwards incompatible API change notes and
60+
actions users need to take to upgrade.
61+
Each version should create new release-note for the version, that will
62+
contained detailed information of the update. This includes `Pull Requests`
63+
list (titles and links), CHANGELOG information related to this version.
64+
65+
## Branching strategy
66+
### General
67+
`master` branch is not associated with any released versions and should not
68+
be used in production. Each released version lives in a separate branch:
69+
- `latest` in `major.x` branch.
70+
- `previous` in `major-1.x` branch.
71+
- `life-support` in `major-2.x` branch.
72+
73+
Minor and patch releases of these versions are released from these branches and
74+
updates are backported from the `master`. Merges to the released version
75+
branches must happen via Pull Requests to give other maintainers and reviewers
76+
time to review and verify what will be released.
77+
78+
Process below will be described as procedurs for the situations:
79+
- release `next` major version candidate.
80+
- release `next` major version. (becomes `latest`)
81+
- release `latest` minor and patch versions.
82+
- release `previous` minor and patch versions.
83+
- release `life-support` minor and patch versions.
84+
85+
Process for the `latest` and `previous` minor/patch releases is the same.
86+
At the same time only these branches should exist in the repo
87+
(Example we have just released `v4.0.0`):
88+
- `master` - active developmeny
89+
- `v4.x` - just become `latest` version.
90+
- `v4.x-proposal` - active backport and PR base.
91+
- `v3.x` - just become `previous` version.
92+
- `v3.x-proposal` - import minor/patch backport and PR base.
93+
- `v2.x` - just become `life-support` version.
94+
- `v2` does not have proposal, because it only supports critical fixes, which
95+
wont go through standard PR release process.
96+
97+
### master branch and package.json version
98+
`master` branch only accumulates changes from PRs and is mostly untested(other
99+
than PR testing). `next` release candidate will branch off from the master.
100+
Package version in the `master` branch will always be set to the `next` but
101+
will have `patch` version set to `99` to signify the unsafe version
102+
(`latestMajor+1.0.99`).
103+
104+
### Release candidate and major release
105+
`master` branch already contains everything that needs to be released
106+
with the `next` version. Instead of directly creating branch to the
107+
`next` version, we create `branch-proposal` to allow brief review
108+
of the contents of the release. The purpose of proposal branches is to allow
109+
other maintainers and reviewers to suggest including something else.
110+
Proposal should not get dragged out and take max 2-3 days before moving on.
111+
At this point we don't want to add more complex things to the release candidate,
112+
only `patch`es until release(feature lock).
113+
114+
Process example (e.g. `latest` was `3.1.0` and we are releasing `4.0.0-rc.1`):
115+
- create branch `4.x-proposal` from the `master`
116+
- update `package.json` version to `5.0.99` in `master` branch.
117+
- update `package.json` version to `4.0.0-rc.1` in `4.x-proposal` branch.
118+
- optional: In case we want to omit some changes from the `master`,
119+
you can also rebase and discard those commits.
120+
- Create Release doc file for the
121+
`docs/release-notes/release-notes-4.0.0-draft.md`.
122+
- Update CHANGELOG file with the incompatibilities and actions to take.
123+
- Create PR: `Release v4.0.0-rc.1` from branch `4.x-proposal` to `4.x`.
124+
- PR description containing list of PRs (similar to release notes)
125+
- We can discuss if we want to add something the release candidate for
126+
testing.
127+
128+
After discussion and review (this should be relatively quick) of the proposal
129+
we do the release of the `release candidate`:
130+
- Merge proposal PR to the `4.x` branch.
131+
- Create the [release files][release-files] for the `4.0.0-rc.1`.
132+
133+
#### Next release candidate
134+
After `release-candidate` is released, we can use `next.x-proposal` branch to
135+
accumulate `backport`s for the `patch`es that are found during testing period.
136+
137+
Process example:
138+
- backport `patch`(es) from the `master` to the `4.x-proposal`.
139+
- update `package.json` version to `4.0.0-rc.2` in the `4.x-proposal`.
140+
- Update Release doc file for the
141+
`docs/release-notes/release-notes-4.0.0-draft.md`.
142+
- Update CHANGELOG file with the incompatibilities and actions to take.
143+
(should not be any)
144+
- Create PR `Release v4.0.0-rc.2` from branch `4.x-proposal` to `4.x`.
145+
- PR lists new PRs that are being added.
146+
- Quick review and merge
147+
- Create the [release files][release-files] for the `4.0.0-rc.2`.
148+
149+
#### Release the major version
150+
Above process continues until last week where we do the actual release:
151+
- update `package.json` version to `4.0.0` in the `4.x-proposal` branch.
152+
- Rename relase doc file from
153+
`docs/release-notes/release-notes-4.0.0-draft.md` to
154+
`docs/release-notes/release-notes-4.0.0.md`
155+
- CHANGELOG should be up to date.
156+
- Create PR `Release v4.0.0` from the branch `4.x-proposal` to `4.x`.
157+
- PR list from prev PRs.
158+
- Final review before release
159+
- [Release files][release-files] for the `4.0.0`
160+
- Update [schedule][schedule] if necessary
161+
162+
### Release minor and patches
163+
This applies to all minor and patches that are being backported to the
164+
`latest`, `previous` versions. Example `v4.0.0` is `latest` and we want to
165+
release minor(process is the same for `previous` minor and patch releases):
166+
- update `package.json` version to `4.1.0` in the `4.x-proposal` branch.
167+
- Create Release doc file `docs/release-notes/release-notes-4.1.0.md`.
168+
- NO CHANGES TO CHANGELOG - this is minor.
169+
- Create PR `Release v4.1.0` from the branch `4.x-proposal` to `4.x`.
170+
- PR description containing list of PRs (similar to release notes)
171+
- We can discuss if we want to add something the release candidate for
172+
testing.
173+
- Review and merge.
174+
- Tag `v4.1.0` from the `4.x`.
175+
- [Release files][release-files] for the `4.1.0`.
176+
177+
[release-files]: ./release-files.md
178+
[schedule]: ./release-schedule.md

‎docs/release-schedule.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Maintenance period
2+
==================
3+
4+
| Version | Release Date | Maintenance End | End of Life |
5+
| ------- | ------------ | --------------- | ----------- |
6+
| v3.x | 2021-10-14 | 2022-10-01 | 2023-04-01 |
7+
| v4.x | 2022-04-30 | 2022-04-01 | 2023-10-01 |
8+
| v5.x | 2022-10-31 | 2022-10-01 | 2024-04-01 |
9+
| v6.x | 2023-04-30 | after v8.0 | after v9.0 |

‎lib/pkg.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ pkg.cfg = `${pkg.core}.conf`;
7070
* @default
7171
*/
7272

73-
pkg.version = '3.0.1';
73+
pkg.version = require('../package.json').version;
7474

7575
/**
7676
* Repository URL.

0 commit comments

Comments
 (0)