Skip to content

Prerelease checklist #16244

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 15, 2025
+56 −25
Merged

Prerelease checklist #16244

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0544fd1
ReleaseChecklist: Announcing releases on EF Discord is no longer poss…
cameel Oct 10, 2025
6cd81ce
ReleaseChecklist: Wording tweaks
cameel Oct 10, 2025
b05924e
ReleaseChecklist: Add a separate checklist for prereleases
cameel Oct 10, 2025
b02d176
installing-solidity.rst: Update information about prerelases
cameel Oct 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 42 additions & 12 deletions ReleaseChecklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this section be moved up to be before ## Full release? Also, when creating a checklist prior to a (pre)release, is only the relevant section copied to hackmd/notes? E.g. if we're doing a full release, do we just copy the ## Full release section?

Copy link
Collaborator Author

@cameel cameel Oct 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this section be moved up to be before ## Full release?

I think it fits better at the end. The release is the main thing, requirements are based primarily on it, etc. The prerelease checklist is also more concise because the assumption is that you read the release checklist first - this would not work the other way around.

Also, when creating a checklist prior to a (pre)release, is only the relevant section copied to hackmd/notes? E.g. if we're doing a full release, do we just copy the ## Full release section?

Yeah, not much point including the requirements. They are something to be checked beforehand, not during the release.

- [ ] 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`.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that this script is a part of #16246.

- [ ] 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`.
Comment on lines +142 to +143
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we also include the source tarball in a prerelease?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, let's. The github archives don't contain the submodule sources so otherwise we have an incomplete set of sources to build it as reference.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, ok, though I'm not sure we'd ever really want to build it as a reference. The whole point of a prerelease are the binaries. We don't prepare a source archive for nightlies either.

- [ ] 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).
Comment on lines +149 to +152
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a undecided about this bit. On one hand, we want prereleases to be super light, so comms should be optional. On the other hand not telling anyone defeats the point, so we should mention it somewhere.

I think what we want it to only advertise as much as needed to reach the people who we expect feedback from.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would be the typical delay between a prerelease and a full release?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a week at the minimum. Not much point doing one when we have a full release just around the corner.

Hard to say what the maximum would be. They won't be regular so it can be anything.

- [ ] 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 :).
27 changes: 14 additions & 13 deletions docs/installing-solidity.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand All @@ -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>`.