Merge pull request #16244 from argotorg/prerelease-checklist

Prerelease checklist

Author: cameel

ReleaseChecklist.md

@@ -1,6 +1,6 @@
-## Checklist for making a release:
+# Checklist for making a Solidity release
 
-### Requirements
+## Requirements
 - [ ] GitHub account with access to [solidity](https://github.com/argotorg/solidity), [solc-js](https://github.com/argotorg/solc-js),
       [solc-bin](https://github.com/argotorg/solc-bin), [solidity-website](https://github.com/argotorg/solidity-website).
 - [ ] DockerHub account with push rights to the [`solc` image](https://hub.docker.com/r/ethereum/solc).
@@ -12,6 +12,8 @@
 - [ ] Access to the [solidity_lang Twitter account](https://twitter.com/solidity_lang).
 - [ ] [Reddit](https://www.reddit.com) account that is at least 10 days old with a minimum of 20 comment karma (`/r/ethereum` requirements).
 
+## Full release
+
 ### Pre-flight checks
 At least a day before the release:
 - [ ] Run `make linkcheck` from within `docs/` and fix any broken links it finds.
@@ -59,19 +61,19 @@ At least a day before the release:
 - [ ] Thank voluntary contributors in the GitHub release notes.
       Use `scripts/list_contributors.sh v<previous version>` to get initial list of names.
       Remove different variants of the same name manually before using the output.
-- [ ] Check that all tests on the latest commit in `develop` are green.
+- [ ] Check that all tests on the latest commit on `develop` are green.
 - [ ] Click the `Publish release` button on the release page, creating the tag.
       **Important: Must not be done before all the PRs, including changelog cleanup and date, are merged.**
 - [ ] Wait for the CI runs on the tag itself.
 
 ### Upload Release Artifacts and Publish Binaries
 - [ ] Switch to the tag that archives have to be created for.
-- [ ] Create the `prerelease.txt` file: (`echo -n > prerelease.txt`).
-- [ ] Run `scripts/create_source_tarball.sh` while being on the tag to create the source tarball. This will create the tarball in a directory called `upload`.
-- [ ] Take the tarball from the upload directory (its name should be `solidity_x.x.x.tar.gz`, otherwise `prerelease.txt` was missing in the step before) and upload the source tarball to the release page.
-- [ ] Take the `github-binaries.tar` tarball from `c_release_binaries` run of the tagged commit in circle-ci and add all binaries from it to the release page.
+- [ ] Create the `prerelease.txt` file: `echo -n > prerelease.txt`.
+- [ ] Run `scripts/create_source_tarball.sh` to create the source tarball. This will create the tarball in a directory called `upload`.
+- [ ] Take the tarball from the upload directory (its name should be `solidity_x.x.x.tar.gz`, otherwise `prerelease.txt` was missing in the step before) and upload it to the release page.
+- [ ] Take the `github-binaries.tar` tarball from `c_release_binaries` run of the tagged commit on Circle CI and add all binaries from it to the release page.
       Make sure it contains four binaries: `solc-windows.exe`, `solc-macos`, `solc-static-linux` and `soljson.js`.
-- [ ] Take the `solc-bin-binaries.tar` tarball from `c_release_binaries` run of the tagged commit in circle-ci and add all binaries from it to solc-bin.
+- [ ] Take the `solc-bin-binaries.tar` tarball from `c_release_binaries` run of the tagged commit on Circle CI and add all binaries from it to solc-bin.
 - [ ] Run `npm install` if you've got a clean checkout of the solc-bin repo.
 - [ ] Run `npm run update -- --reuse-hashes` in `solc-bin` and verify that the script has updated `list.js`, `list.txt` and `list.json` files correctly and that symlinks to the new release have been added in `solc-bin/wasm/` and `solc-bin/emscripten-wasm32/`.
 - [ ] Create a pull request in solc-bin and merge.
@@ -101,7 +103,7 @@ At least a day before the release:
 - [ ] Increment the version number, create a pull request for that, merge it after tests succeeded.
 - [ ] Create a tag using `git tag --annotate v$VERSION` and push it with `git push --tags`.
 - [ ] Wait for the CI runs on the tag itself.
-- [ ] Take the `solc-x.y.z.tgz` artifact from `build-package` run on the tagged commit in circle-ci.
+- [ ] Take the `solc-x.y.z.tgz` artifact from `build-package` run on the tagged commit on Circle CI.
       Inspect the tarball to ensure that it contains an up-to-date compiler binary (`soljson.js`).
 - [ ] Run `npm publish solc-x.y.z.tgz` to publish the newly created tarball.
 
@@ -116,9 +118,37 @@ At least a day before the release:
 - [ ] Announce on [Fosstodon](https://fosstodon.org/@solidity/), including links to the release and the blog post.
 - [ ] Share the announcement on Reddit in [`/r/ethdev`](https://reddit.com/r/ethdev/), cross-posted to [`/r/ethereum`](https://reddit.com/r/ethereum/).
 - [ ] Share the announcement on the [Solidity forum](https://forum.soliditylang.org) in the `Announcements` category.
-- [ ] Share the announcement on [Project Updates](https://discord.com/channels/420394352083337236/798974456704925696)
-- [ ] Share the announcement on [`#solidity` channel on Matrix](https://matrix.to/#/#ethereum_solidity:gitter.im)
-- [ ] Share the announcement on [`#solc-tooling`](https://matrix.to/#/#solc-tooling:matrix.org)
+- [ ] Share the announcement on [`#solidity` channel on Matrix](https://matrix.to/#/#ethereum_solidity:gitter.im).
+- [ ] Share the announcement on [`#solc-tooling`](https://matrix.to/#/#solc-tooling:matrix.org).
 - [ ] If anything went wrong this time, mention it in [Learning from Past Releases](https://notes.argot.org/@solidity-release-mistakes).
 - [ ] Bump vendored dependencies.
 - [ ] Lean back, wait for bug reports and repeat from step 1 :).
+
+## Prerelease
+- [ ] Check that all tests on the latest commit on `develop` or `breaking` branch (whichever was chosen for the prerelease) are green.
+- [ ] Create a [release on GitHub](https://github.com/argotorg/solidity/releases/new).
+      - Set the target to the `develop` or `breaking` branch and the tag to the new version with a prerelease suffix, e.g. `v0.8.5-pre.6`.
+          Version matches the next release (`develop`) or the next breaking release (`breaking`).
+          The prerelease number in the suffix is 1-based, sequential, resets after a full release and is counted separately for `develop` and `breaking`.
+      - Include the following warning: `**The release is still in progress. You may see broken links and binaries may not yet be available from all sources.**`.
+      - Include the current, incomplete changelog.
+      - Check the `Set as a pre-release` box.
+      - Click the `Publish release` button on the release page, creating the tag.
+- [ ] Wait for the CI runs on the tag itself.
+- [ ] Switch to the tag that archives have to be created for.
+- [ ] Create the `prerelease.txt` file: `scripts/prerelease_suffix.sh pre "$(git describe --tags --exact-match)" > prerelease.txt`.
+- [ ] Run `scripts/create_source_tarball.sh` to create the source tarball. This will create the tarball in a directory called `upload`.
+- [ ] Take the tarball from the upload directory (its name should be `solidity_x.x.x-pre.N.tar.gz`, if `prerelease.txt` was created correctly) and upload it to the release page.
+- [ ] Take the `github-binaries.tar` tarball from `c_release_binaries` run of the tagged commit on Circle CI and add all binaries from it to the release page.
+      Make sure it contains four binaries: `solc-windows.exe`, `solc-macos`, `solc-static-linux` and `soljson.js`.
+- [ ] Take the `solc-bin-binaries.tar` tarball from `c_release_binaries` run of the tagged commit on Circle CI and add all binaries from it to solc-bin.
+- [ ] Run `npm install` if you've got a clean checkout of the solc-bin repo.
+- [ ] Run `npm run update -- --reuse-hashes` in `solc-bin` and verify that the script has updated `list.js`, `list.txt` and `list.json` files correctly and that symlinks to the new release have been added in `solc-bin/wasm/` and `solc-bin/emscripten-wasm32/`.
+- [ ] Create a pull request in solc-bin and merge.
+- [ ] Remove "still in progress" warning from the [release notes](https://github.com/argotorg/solidity/releases).
+- [ ] Mention it on [Twitter](https://twitter.com/solidity_lang).
+- [ ] Mention it on [Fosstodon](https://fosstodon.org/@solidity/).
+- [ ] Mention it on [`#solidity` channel on Matrix](https://matrix.to/#/#ethereum_solidity:gitter.im).
+- [ ] Mention it on [`#solc-tooling`](https://matrix.to/#/#solc-tooling:matrix.org).
+- [ ] If anything went wrong this time, mention it in [Learning from Past Releases](https://notes.argot.org/@solidity-release-mistakes).
+- [ ] Lean back, wait for bug reports and repeat from step 1 :).

docs/installing-solidity.rst

@@ -14,13 +14,12 @@ addition, patch-level releases with major release 0 (i.e. 0.x.y) will not
 contain breaking changes. That means code that compiles with version 0.x.y
 can be expected to compile with 0.x.z where z > y.
 
-In addition to releases, we provide **nightly development builds** to make
-it easy for developers to try out upcoming features and
-provide early feedback. Note, however, that while the nightly builds are usually
-very stable, they contain bleeding-edge code from the development branch and are
-not guaranteed to be always working. Despite our best efforts, they might
-contain undocumented and/or broken changes that will not become a part of an
-actual release. They are not meant for production use.
+In addition to releases, we provide **prereleases** and **nightly development builds** to make it
+easy for developers to try out upcoming features and provide early feedback.
+Note that such builds contain bleeding-edge code from the development branch and are not guaranteed
+to be of the same quality as full releases.
+Despite our best efforts, they might contain undocumented and/or broken changes that will not
+become a part of an actual release. They are not meant for production use.
 
 When deploying contracts, you should use the latest released version of Solidity. This
 is because breaking changes, as well as new features and bug fixes are introduced regularly.
@@ -544,7 +543,7 @@ The Version String in Detail
 The Solidity version string contains four parts:
 
 - the version number
-- pre-release tag, usually set to ``develop.YYYY.MM.DD`` or ``nightly.YYYY.MM.DD``
+- pre-release tag, usually set to ``develop.YYYY.MM.DD``, ``pre.N`` or ``nightly.YYYY.MM.DD``
 - commit in the format of ``commit.GITHASH``
 - platform, which has an arbitrary number of items, containing details about the platform and compiler
 
@@ -553,24 +552,26 @@ If there are local modifications, the commit will be postfixed with ``.mod``.
 These parts are combined as required by SemVer, where the Solidity pre-release tag equals to the SemVer pre-release
 and the Solidity commit and platform combined make up the SemVer build metadata.
 
-A release example: ``0.4.8+commit.60cc1668.Emscripten.clang``.
+Examples:
 
-A pre-release example: ``0.4.9-nightly.2017.1.17+commit.6ecb4aa3.Emscripten.clang``
+- release: ``0.4.8+commit.60cc1668.Emscripten.clang``
+- pre-release: ``0.4.9-pre.3+commit.fb60450bc.Emscripten.clang``
+- nightly build: ``0.4.9-nightly.2017.1.17+commit.6ecb4aa3.Emscripten.clang``
 
 Important Information About Versioning
 ======================================
 
 After a release is made, the patch version level is bumped, because we assume that only
 patch level changes follow. When changes are merged, the version should be bumped according
 to SemVer and the severity of the change. Finally, a release is always made with the version
-of the current nightly build, but without the ``prerelease`` specifier.
+of the current build, but without the ``prerelease`` specifier.
 
 Example:
 
 1. The 0.4.0 release is made.
-2. The nightly build has a version of 0.4.1 from now on.
+2. Nightly builds and preerelases have a version of 0.4.1 from now on.
 3. Non-breaking changes are introduced --> no change in version.
 4. A breaking change is introduced --> version is bumped to 0.5.0.
 5. The 0.5.0 release is made.
 
-This behavior works well with the  :ref:`version pragma <version_pragma>`.
+This behavior works well with the :ref:`version pragma <version_pragma>`.