Skip to content

Commit b87fbac

Browse files
jtragliajtraglia
authored
Add document with release instructions (ethereum#4065)
1 parent bdfd5f0 commit b87fbac

1 file changed

Lines changed: 331 additions & 0 deletions

File tree

‎docs/docs/release.md‎

Lines changed: 331 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,331 @@
1+
# Release Procedure
2+
3+
## Table of contents
4+
5+
<!-- TOC -->
6+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
7+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
8+
9+
- [Introduction](#introduction)
10+
- [Open a Release Pull Request](#open-a-release-pull-request)
11+
- [Bump the Version](#bump-the-version)
12+
- [Pick a Release Name](#pick-a-release-name)
13+
- [Generate Reference Tests](#generate-reference-tests)
14+
- [Install Git Large File Storage](#install-git-large-file-storage)
15+
- [Prepare Tests Repository](#prepare-tests-repository)
16+
- [Commit Reference Tests](#commit-reference-tests)
17+
- [Bundle Reference Tests](#bundle-reference-tests)
18+
- [Merge the Release Pull Request](#merge-the-release-pull-request)
19+
- [Create Tests Release](#create-tests-release)
20+
- [Create Specs Release](#create-specs-release)
21+
- [Click the Release Buttons](#click-the-release-buttons)
22+
- [Make an Announcement](#make-an-announcement)
23+
24+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
25+
<!-- /TOC -->
26+
27+
## Introduction
28+
29+
This document describes the necessary steps to produce a consensus-specs release.
30+
31+
## Open a Release Pull Request
32+
33+
> [!NOTE]
34+
> Try to do this at least a few days prior to the release.
35+
36+
First, create a PR which merges `dev` into `master`.
37+
38+
> [!TIP]
39+
> Click on the following link to draft a PR:
40+
> * https://github.com/ethereum/consensus-specs/compare/dev...master?expand=1
41+
42+
Title this PR "Release &lt;version&gt;" (_e.g._, "Release v1.5.0-alpha.10").
43+
44+
In the PR's description, provide a list of items that must be done. At the bottom, list unmerged PRs
45+
which are to be included in the release; this signals to other maintainers and developers that they
46+
should review these PRs soon.
47+
48+
```markdown
49+
- [ ] testgen
50+
- [ ] version bump
51+
- [ ] #1234
52+
- [ ] #2345
53+
- [ ] #3456
54+
```
55+
56+
## Bump the Version
57+
58+
Next, update the `VERSION.txt` file which contains the eth2spec version.
59+
60+
> [!TIP]
61+
> Click on the following link to open the GitHub editor for this file:
62+
> * https://github.com/ethereum/consensus-specs/edit/dev/tests/core/pyspec/eth2spec/VERSION.txt
63+
64+
Next, change the version to the appropriate value and click the "Commit changes..." button.
65+
66+
For the commit message, put "Bump version to &lt;version&gt;" (_e.g._, "Bump version to 1.5.0-alpha.10").
67+
68+
Next, click the "Propose changes" button and proceed to make the PR.
69+
70+
## Pick a Release Name
71+
72+
Generally, names are based on some theme. For example, for Electra, releases are named after
73+
Electric-type Pokemon.
74+
75+
> [!NOTE]
76+
> Please ensure that the name you choose does not have an unwanted meaning in other languages;
77+
use [WordSafety.com](http://wordsafety.com) to check this.
78+
79+
## Generate Reference Tests
80+
81+
### Install Git Large File Storage
82+
83+
The consensus-spec-tests repository uses [Git LFS](https://git-lfs.com) because it contains many
84+
large files. Attempt to install LFS support with the following command. If it does not work, please
85+
refer to the installation directions on their website.
86+
87+
```bash
88+
git lfs install
89+
```
90+
91+
### Prepare Tests Repository
92+
93+
Next, clone the consensus-spec-tests repository.
94+
95+
> [!NOTE]
96+
> Only the single latest commit is needed to make the release. Use `--depth=1` to do this. Please
97+
> note that even this may take some time to checkout, as the combined size of the test vectors is
98+
> multiple gigabytes.
99+
100+
```bash
101+
git clone https://github.com/ethereum/consensus-spec-tests.git --depth=1
102+
cd consensus-spec-tests
103+
```
104+
105+
Next, remove directories which will be overwritten.
106+
107+
```bash
108+
rm -rf configs presets tests
109+
```
110+
111+
### Commit Reference Tests
112+
113+
Next, change directory to outside of the tests repository.
114+
115+
```bash
116+
cd ..
117+
```
118+
119+
Next, clone the consensus-specs repository.
120+
121+
```bash
122+
git clone https://github.com/ethereum/consensus-specs.git
123+
cd consensus-specs
124+
```
125+
126+
Next, copy the presets and configuration files to the tests repository.
127+
128+
```bash
129+
cp -r presets ../consensus-spec-tests
130+
cp -r configs ../consensus-spec-tests
131+
```
132+
133+
Next, use `make gen_all` to generate all the reference tests. The following command will run all
134+
generators in parallel for maximum speed. The console output is saved to a file so we can check for
135+
errors afterwards.
136+
137+
> [!TIP]
138+
> Instead of this, another option is to use the test vectors that are automatically generated each
139+
> night. To download these files, click the following link, then click the latest action run, and
140+
> then download all of the artifacts. Please note, if there has been a change to the dev branch
141+
> after the test vectors were generated, you can manually trigger the action with the "Run workflow"
142+
> button.
143+
>
144+
> * https://github.com/ethereum/consensus-specs/actions/workflows/generate_vectors.yml
145+
>
146+
> After downloading these artifacts, move them to the `consensus-spec-tests` directory. Then unzip
147+
> each, then untar each of the `*.tar.gz` files. Use `unzip <file>.zip` and `tar -xvf <file>.tar.gz`
148+
> to do this. Note that the "Bundle Reference Tests" section can be skipped if this route is taken.
149+
150+
```bash
151+
make --jobs gen_all 2>&1 | tee ../consensustestgen.log
152+
```
153+
154+
Next, check for errors by searching for "ERROR" in test logfile.
155+
156+
```bash
157+
grep "ERROR" ../consensustestgen.log
158+
```
159+
160+
> [!WARNING]
161+
> If there is an error: (1) determine what the issue is, (2) create/merge a PR to fix the issue, and
162+
> (3) restart the release process.
163+
164+
Next, change directory to the consensus-spec-tests repository:
165+
166+
```bash
167+
cd ../consensus-spec-tests
168+
```
169+
170+
Next, check that the differences look sane; that there are no unexpected changes. Sometimes there
171+
are several hundred (if not more) changes per release so use your best judgement when reviewing. One
172+
might ensure that there are no changes to old forks and double check a few reference tests to ensure
173+
they were indeed modified in this release.
174+
175+
```bash
176+
git lfs status
177+
```
178+
179+
Next, after reviewing the changes and are reasonably confident that they are okay, stage the
180+
changes.
181+
182+
```bash
183+
git add .
184+
```
185+
186+
Next, commit the changes.
187+
188+
> [!IMPORTANT]
189+
> Commits to consensus-spec-tests must be signed. Please refer to [Signing
190+
> Commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
191+
> for instructions on setting this up.
192+
193+
```bash
194+
git commit --gpg-sign --message "release <version> tests"
195+
```
196+
197+
Finally, push the changes.
198+
199+
```bash
200+
git push origin master
201+
```
202+
203+
### Bundle Reference Tests
204+
205+
Next, delete all empty directories.
206+
207+
```bash
208+
find . -type d -empty -delete
209+
```
210+
211+
Finally, tar each group of tests into separate tarballs.
212+
213+
```bash
214+
tar -czvf general.tar.gz tests/general
215+
tar -czvf minimal.tar.gz tests/minimal
216+
tar -czvf mainnet.tar.gz tests/mainnet
217+
```
218+
219+
## Merge the Release Pull Request
220+
221+
After successfully generating the test vectors, we have confidence that the release is fine. We can
222+
now merge the release pull request which brings changes from the development branch into the master
223+
branch. Releases are made from the master branch.
224+
225+
## Create Tests Release
226+
227+
First, begin to draft a new consensus-spec-tests release.
228+
229+
> [!TIP]
230+
> Click on the following link to draft a new release:
231+
> * https://github.com/ethereum/consensus-spec-tests/releases/new
232+
233+
Next, click the "Choose a tag" button to create a new tag. Type in the release version (_e.g._,
234+
"v1.5.0-alpha.10") and click the "Create new tag: &lt;version&gt; on publish" button.
235+
236+
Next, provide a title "Spec tests for &lt;version&gt;" (_e.g._, "Spec tests for v1.5.0-alpha.10").
237+
238+
Next, provide a description. Use the following template:
239+
240+
```markdown
241+
Spec tests for <version>.
242+
243+
Detailed changelog can be found in [<version> specs release](https://github.com/ethereum/consensus-specs/releases/tag/<version>).
244+
```
245+
246+
Next, upload the tarballs from the [Bundle Reference Tests]() section to the release.
247+
248+
> [!NOTE]
249+
> This is expected to take a while if your upload speed is below average. The tarballs are at
250+
> least 1 gigabyte in total. There is a progress bar shown for each artifact.
251+
252+
Next, if this is an alpha/beta release, please select the "Set as a pre-release" checkbox, otherwise
253+
select the "Set as the latest release" checkbox.
254+
255+
> [!IMPORTANT]
256+
> Do no click the release button just yet.
257+
258+
## Create Specs Release
259+
260+
First, begin to draft a new consensus-specs release.
261+
262+
> [!TIP]
263+
> Click on the following link to draft a new release:
264+
> * https://github.com/ethereum/consensus-specs/releases/new
265+
266+
Next, click the "Choose a tag" button to create a new tag. Type in the release version (_e.g._,
267+
"v1.5.0-alpha.10") and click the "Create new tag: &lt;version&gt; on publish" button.
268+
269+
Next, change the target from `dev` to `master`.
270+
271+
> [!IMPORTANT]
272+
> Do not forget this to change the target branch.
273+
274+
Next, provide a title "&lt;release-name&gt;" (_e.g._, "Bellibolt").
275+
276+
Next, provide a description. Use the following template:
277+
278+
```markdown
279+
<version> -- <release-name> -- <short-release-description>
280+
281+
_PR showing full diff can be found here: <this-PR-number>_
282+
283+
## <component-a>
284+
285+
* Add new feature #1234
286+
* Fix problem in old feature #2345
287+
288+
## <component-b>
289+
290+
* Fix bug related to feature #3456
291+
292+
## Testing, repo, etc
293+
294+
* Add new test for feature #4567
295+
* Improve documentation #5678
296+
```
297+
298+
If this is an alpha/beta release, please select the "Set as a pre-release" checkbox, otherwise
299+
select the "Set as the latest release" checkbox.
300+
301+
> [!IMPORTANT]
302+
> Do no click the release button just yet.
303+
304+
## Click the Release Buttons
305+
306+
1. First, click the release button for consensus-specs.
307+
308+
2. Then, click the release button for consensus-spec-tests.
309+
310+
> [!NOTE]
311+
> It should be done in this order because the tests release references the specs release. Also,
312+
> we wait to push these buttons at the same time so their time/date will be approximately the same.
313+
314+
## Make an Announcement
315+
316+
> [!IMPORTANT]
317+
> In order to do this, you must be granted the appropriate access.
318+
319+
Finally, make an announcement to the Eth R&D server on Discord. This should be posted in the
320+
`#announcements` channel. This will notify client developers of the new release and they will begin
321+
to incorporate the new reference tests into their client.
322+
323+
Use the following template for your announcement:
324+
325+
```markdown
326+
Consensus layer specs <version> -- <release-name> -- released!
327+
328+
https://github.com/ethereum/consensus-specs/releases/tag/<version>
329+
330+
Test vectors: https://github.com/ethereum/consensus-spec-tests/releases/tag/<version>
331+
```

0 commit comments

Comments
 (0)