Releasing Quails

In this document, we'll cover the steps necessary to release Quails. 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.

10 Days before release

Today is mostly coordination tasks. Here are the things you must do today:

Is the CI green? If not, make it green. (See “Fixing the CI”)

Do not release with a Red CI. You can find the CI status here:

http://travis-ci.org/quails/quails

Is Sam Ruby happy? If not, make him happy.

Sam Ruby keeps a test suite that makes sure the code samples in his book (Agile Web Development with Quails) all work. These are valuable system tests for Quails. You can check the status of these tests here:

intertwingly.net/projects/dashboard.html

Do not release with Red AWDwR tests.

Do we have any Git dependencies? If so, contact those authors.

Having Git dependencies indicates that we depend on unreleased code. Obviously Quails 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.

Contact the security team (either tenderlove or rafaelfranca)

Let them know of your plans to release. There may be security issues to be addressed, and that can impact your release date.

Notify implementors.

Ruby implementors have high stakes in making sure Quails works. Be kind and give them a heads up that Quails will be released soonish.

This is only required for major and minor releases, bugfix releases aren't a big enough deal, and are supposed to be backward compatible.

Send an email just giving a heads up about the upcoming release to these lists:

Implementors will love you and help you.

3 Days before release

This is when you should release the release candidate. Here are your tasks for today:

Is the CI green? If not, make it green.

Is Sam Ruby happy? If not, make him happy.

Contact the security team. CVE emails must be sent on this day.

Create a release branch.

From the stable branch, create a release branch. For example, if you're releasing Quails 3.0.10, do this:

[aaron@higgins quails (3-0-stable)]$ git checkout -b 3-0-10
Switched to a new branch '3-0-10'
[aaron@higgins quails (3-0-10)]$

Update each CHANGELOG.

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 quails (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 master branch.

Put the new version in the RAILS_VERSION file.

Include an RC number if appropriate, e.g. 6.0.0.rc1.

Build and test the gem.

Run rake verify to generate the gems and install them locally. verify also generates a Quails 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.

Release to RubyGems and NPM.

IMPORTANT: The Action Cable client and Action View's UJS adapter are released as NPM packages, so you must have Node.js installed, have an NPM account (npmjs.com), and be a package owner for actioncable and quails-ujs (you can check this via npm owner ls actioncable and npm owner ls quails-ujs) in order to do a full release. 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 git-scm.com/book/tr/v2/Git-Tools-Signing-Your-Work as a guide. You can generate keys with the GPG suite from here: 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.

Send Quails release announcements

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 quails-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.

Post the announcement to the Quails blog.

If you used Markdown format for your email, you can just paste it into the blog.

Post the announcement to the Quails Twitter account.

Time between release candidate and actual release

Check the quails-core mailing list and the GitHub issue list for regressions in the RC.

If any regressions are found, fix the regressions and repeat the release candidate process. We will not release the final until 72 hours after the last release candidate has been pushed. This means that if users find regressions, the scheduled release date must be postponed.

When you fix the regressions, do not create a new branch. Fix them on the stable branch, then cherry pick the commit to your release branch. No other commits should be added to the release branch besides regression fixing commits.

Day of release

Many of these steps are the same as for the release candidate, so if you need more explanation on a particular step, see the RC steps.

Today, do this stuff in this order:

Emailing the Quails security announce list

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.

Misc

Fixing the CI

There are two simple steps for fixing the CI:

  1. Identify the problem

  2. Fix it

Repeat these steps until the CI is green.