Skip to content

ReleaseChecklist.md

Latest commit

 

History

History
148 lines (134 loc) · 12.5 KB

ReleaseChecklist.md

File metadata and controls

148 lines (134 loc) · 12.5 KB

Checklist for making a Solidity release

Requirements

  • GitHub account with access to solidity, solc-js, solc-bin, solidity-website.
  • DockerHub account with push rights to the solc image.
  • Launchpad (Ubuntu One) account with a membership in the "Ethereum" team and a gnupg key for your email in the ethereum.org domain (has to be version 1, gpg2 won't work).
  • Ubuntu/Debian dependencies of the Docker script: docker-buildx.
  • Ubuntu/Debian dependencies of the PPA scripts: devscripts, debhelper, dput, git, wget, ca-certificates.
  • npm Registry account added as a collaborator for the solc package.
  • Access to the solidity_lang Twitter account.
  • Reddit 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. Ignore false positives caused by href anchors and dummy links not meant to work. Note: In order to run the link check, make sure you've built the docs first via docs.sh.
  • Double-check that the most recent docs builds at readthedocs succeeded.
  • Make sure that all merged PRs that should have changelog entries do have them.
  • Rerun CI on the top commits of main branches in all repositories that do not have daily activity by creating a test branch or PR:
    • solc-js
    • solc-bin (make sure the bytecode comparison check did run)
  • (Optional) Create a prerelease in our Ubuntu PPA by following the steps in the PPA section below on develop rather than on a tag. This is recommended especially when dealing with PPA for the first time, when we add a new Ubuntu version or when the PPA scripts were modified in this release cycle.
  • Verify that the release tarball of solc-js works. Bump version locally, add soljson.js from CI, build it, compare the file structure with the previous version, install it locally and try to use it.
  • Review Learning from Past Releases to make sure you don't repeat the same mistakes.

Drafts

At least a day before the release:

  • Create a draft PR to sort the changelog.
  • Create draft PRs to bump version in solidity and solc-js. Note: The solc-js PR won't pass CI checks yet because it depends on the soljson binary from solc-bin.
  • Create a draft of the release on github.
  • Create a draft PR to update soliditylang.org.
  • Create drafts of blog posts.
  • Prepare drafts of Twitter, Reddit and Solidity Forum announcements.

Blog Post

  • Create a post on solidity-website in the Releases category and explain some of the new features or concepts.
  • Create a post on solidity-website in the Security Alerts category in case of important bug(s).
  • Get the posts reviewed and approved before the release starts.

Changelog

  • Sort the changelog entries alphabetically and correct any errors you notice. Commit it.
  • Update the changelog to include a release date.
  • Run scripts/update_bugs_by_version.py to regenerate bugs_by_version.json from the changelog and bugs.json. Make sure that the resulting bugs_by_version.json has a new, empty entry for the new version.
  • Commit changes, create a pull request and wait for the tests. Then merge it.
  • Copy the changelog into the release blog post.

Create the Release

  • Create a release on GitHub. Set the target to the develop branch and the tag to the new version, e.g. v0.8.5. 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.**. Do not publish it yet - click the Save draft button instead.
  • 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 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

  • Take the source tarball (solidity_x.x.x.tar.gz) from c_source_tarball run of the tagged commit on Circle CI 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 five binaries: solc-windows.exe, solc-macos, solc-static-linux, solc-static-linux-arm, 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.

Homebrew and MacOS

Docker

  • Make sure docker-buildx is installed.
  • Run ./scripts/docker_deploy_manual.sh v$VERSION.

PPA

  • Create .release_ppa_auth at the root of your local Solidity checkout and set LAUNCHPAD_EMAIL and LAUNCHPAD_KEYID to your key's email and key id.
  • Double-check that the DISTRIBUTIONS list in scripts/release_ppa.sh contains the most recent versions of Ubuntu.
  • Run scripts/release_ppa.sh v$VERSION to create the PPA release. This will create a single package containing static binary for older Ubuntu versions in the ~ethereum/ethereum-static PPA and separate packages with dynamically-linked binaries for recent versions (those listed in DISTRIBUTIONS) in the ~ethereum/ethereum PPA.
  • Wait for the build to be finished and published for all architectures (currently we only build for amd64, but we may add arm in the future). SERIOUSLY: DO NOT PROCEED EARLIER!!!
  • After the package with the static build is published, use it to create packages for older Ubuntu versions. Copy the static package to the ~ethereum/ethereum PPA for the destination series Trusty, Xenial, Bionic, and Focal while selecting Copy existing binaries.

Release solc-js

  • Wait until solc-bin was properly deployed. You can test this via remix - a test run through remix is advisable anyway.
  • 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 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.

Post-release

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.
    • 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.
  • Take the source tarball (solidity_x.x.x-pre.N.tar.gz) from c_source_tarball run of the tagged commit on Circle CI 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 five binaries: solc-windows.exe, solc-macos, solc-static-linux, solc-static-linux-arm 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.
  • Mention it on Twitter.
  • Mention it on Fosstodon.
  • Mention it on #solidity channel on Matrix.
  • Mention it on #solc-tooling.
  • If anything went wrong this time, mention it in Learning from Past Releases.
  • Lean back, wait for bug reports and repeat from step 1 :).