In this document, we'll cover the steps necessary to release Rails. Each section contains steps to take during that time before the release. The times suggested in each header are just that: suggestions. However, they should really be considered as minimums.
Today is mostly coordination tasks. Here are the things you must do today:
Do not release with a Red CI. You can find the CI status here:
https://buildkite.com/rails/rails
Having Git dependencies indicates that we depend on unreleased code. Obviously Rails cannot be released when it depends on unreleased code. Contact the authors of those particular gems and work out a release date that suits them.
Let them know of your plans to release.
Many times commits are made without the CHANGELOG being updated. You should review the commits since the last release, and fill in any missing information for each CHANGELOG.
You can review the commits for the 3.0.10 release like this:
[aaron@higgins rails (3-0-10)]$ git log v3.0.9..
If you're doing a stable branch release, you should also ensure that all of the CHANGELOG entries in the stable branch are also synced to the main branch.
Include an RC number if appropriate, e.g. 6.0.0.rc1.
Run rake verify to generate the gems and install them locally. verify also
generates a Rails app with a migration and boots it to smoke test with in your
browser.
This will stop you from looking silly when you push an RC to rubygems.org and then realize it is broken.
IMPORTANT: Several gems have JavaScript components that are released as npm
packages, so you must have Node.js installed, have an npm account (npmjs.com),
and be a package owner for @rails/actioncable, @rails/actiontext,
@rails/activestorage, and @rails/ujs. You can check this by making sure your
npm user (npm whoami) is listed as an owner (npm owner ls <pkg>) of each
package. Do not release until you're set up with npm!
The release task will sign the release tag. If you haven't got commit signing set up, use https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work as a guide. You can generate keys with the GPG suite from here: https://gpgtools.org.
Run rake changelog:header to put a header with the new version in every
CHANGELOG. Don't commit this, the release task handles it.
Run rake release. This will populate the gemspecs and npm package.json with
the current RAILS_VERSION, commit the changes, tag it, and push the gems to
rubygems.org.
Write a release announcement that includes the version, changes, and links to GitHub where people can find the specific commit list. Here are the mailing lists where you should announce:
Use Markdown format for your announcement. Remember to ask people to report issues with the release candidate to the rails-core mailing list.
NOTE: For patch releases, there's a rake announce task to generate the release
post. It supports multiple patch releases too:
VERSIONS="5.0.5.rc1,5.1.3.rc1" rake announce
IMPORTANT: If any users experience regressions when using the release candidate, you must postpone the release. Bugfix releases should not break existing applications.
If you used Markdown format for your email, you can just paste it into the blog.
Email the security announce list once for each vulnerability fixed.
You can do this, or ask the security team to do it.
Email the security reports to:
Be sure to note the security fixes in your announcement along with CVE numbers and links to each patch. Some people may not be able to upgrade right away, so we need to give them the security fixes in patch form.
- Blog announcements
- Twitter announcements
- Merge the release branch to the stable branch
- Drink beer (or other cocktail)
There are two simple steps for fixing the CI:
- Identify the problem
- Fix it
Repeat these steps until the CI is green.