2011-08-04 18:27:26 +00:00
|
|
|
= Releasing Rails
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
== 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/#!/rails/rails
|
|
|
|
|
|
|
|
=== 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 Rails) all work. These are valuable integration tests
|
|
|
|
for Rails. You can check the status of his tests here:
|
|
|
|
|
|
|
|
http://intertwingly.net/projects/dashboard.html
|
|
|
|
|
|
|
|
Do not release with Red AWDwR tests.
|
|
|
|
|
2011-11-14 12:08:03 +00:00
|
|
|
=== Are the postgres tests green? If not, make them green
|
|
|
|
|
|
|
|
Currently Travis CI doesn't run the Active Record postgres tests. They are
|
|
|
|
working to resolve this, but in the mean time, it is crucial to ensure that
|
|
|
|
the tests are still green before release.
|
|
|
|
|
2011-08-04 18:27:26 +00:00
|
|
|
=== Do we have any git dependencies? If so, contact those authors.
|
|
|
|
|
|
|
|
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
|
2011-08-13 00:23:16 +00:00
|
|
|
suits them.
|
2011-08-04 18:27:26 +00:00
|
|
|
|
2011-08-04 21:15:45 +00:00
|
|
|
=== Contact the security team (either Koz or tenderlove)
|
|
|
|
|
|
|
|
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 Rails works. Be kind and
|
|
|
|
give them a heads up that Rails will be released soonish.
|
|
|
|
|
|
|
|
Send an email just giving a heads up about the upcoming release to these
|
|
|
|
lists:
|
|
|
|
|
|
|
|
* team@jruby.org
|
|
|
|
* community@rubini.us
|
|
|
|
* rubyonrails-core@googlegroups.com
|
|
|
|
|
|
|
|
Implementors will love you and help you.
|
|
|
|
|
2011-08-04 18:27:26 +00:00
|
|
|
== 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.
|
|
|
|
|
2011-11-14 12:08:03 +00:00
|
|
|
=== Are the postgres tests green? If not, make them green
|
|
|
|
|
2011-08-04 18:27:26 +00:00
|
|
|
=== 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 Rails 3.0.10, do this:
|
|
|
|
|
|
|
|
[aaron@higgins rails (3-0-stable)]$ git checkout -b 3-0-10
|
|
|
|
Switched to a new branch '3-0-10'
|
|
|
|
[aaron@higgins rails (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 rails (3-0-10)]$ git log v3.0.9..
|
|
|
|
|
2011-11-14 11:29:57 +00:00
|
|
|
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.
|
|
|
|
|
2011-08-04 18:27:26 +00:00
|
|
|
=== Update the RAILS_VERSION file to include the RC.
|
|
|
|
|
2011-11-14 17:08:24 +00:00
|
|
|
=== Build and test the gem.
|
|
|
|
|
|
|
|
Run `rake install` to generate the gems and install them locally. Then try
|
|
|
|
generating a new app and ensure that nothing explodes.
|
|
|
|
|
2011-11-18 19:22:18 +00:00
|
|
|
This will stop you from looking silly when you push an RC to rubygems.org and
|
|
|
|
then realise it is broken.
|
2011-11-14 17:08:24 +00:00
|
|
|
|
2011-08-04 18:27:26 +00:00
|
|
|
=== Release the gem.
|
|
|
|
|
|
|
|
IMPORTANT: Due to YAML parse problems on the rubygems.org server, it is safest
|
|
|
|
to use Ruby 1.8 when releasing.
|
|
|
|
|
|
|
|
Run `rake release`. This will populate the gemspecs with data from
|
|
|
|
RAILS_VERSION, commit the changes, tag it, and push the gems to rubygems.org.
|
|
|
|
Here are the commands that `rake release` should use, so you can understand
|
|
|
|
what to do in case anything goes wrong:
|
|
|
|
|
|
|
|
$ rake all:build
|
|
|
|
$ git commit -am'updating RAILS_VERSION'
|
|
|
|
$ git tag -m'tagging rc release' v3.0.10.rc1
|
2011-08-04 21:43:13 +00:00
|
|
|
$ git push
|
|
|
|
$ git push --tags
|
2011-08-04 18:27:26 +00:00
|
|
|
$ for i in $(ls dist); do gem push $i; done
|
|
|
|
|
|
|
|
=== Send Rails 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:
|
|
|
|
|
|
|
|
* rubyonrails-core@googlegroups.com
|
|
|
|
* rubyonrails-talk@googlegroups.com
|
|
|
|
* ruby-talk@ruby-lang.org
|
|
|
|
|
|
|
|
Use markdown format for your announcement. Remember to ask people to report
|
|
|
|
issues with the release candidate to the rails-core mailing list.
|
|
|
|
|
2011-08-04 19:00:06 +00:00
|
|
|
IMPORTANT: If any users experience regressions when using the release
|
2011-08-04 18:27:26 +00:00
|
|
|
candidate, you *must* postpone the release. Bugfix releases *should not*
|
|
|
|
break existing applications.
|
|
|
|
|
|
|
|
=== Post the announcement to the Rails blog.
|
|
|
|
|
|
|
|
If you used markdown format for your email, you can just paste it in to the
|
|
|
|
blog.
|
|
|
|
|
|
|
|
* http://weblog.rubyonrails.org
|
|
|
|
|
|
|
|
=== Post the announcement to the Rails twitter account.
|
|
|
|
|
|
|
|
== Time between release candidate and actual release
|
|
|
|
|
|
|
|
Check the rails-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, so the RC steps.
|
|
|
|
|
2011-08-17 00:39:58 +00:00
|
|
|
Today, do this stuff in this order:
|
|
|
|
|
|
|
|
* Apply security patches to the release branch
|
|
|
|
* Update CHANGELOG with security fixes.
|
|
|
|
* Update RAILS_VERSION to remove the rc
|
2011-11-14 17:08:24 +00:00
|
|
|
* Build and test the gem
|
2011-08-17 00:39:58 +00:00
|
|
|
* Release the gems
|
|
|
|
* Email security lists
|
|
|
|
* Email general announcement lists
|
2011-08-16 23:30:29 +00:00
|
|
|
|
2011-08-17 00:39:58 +00:00
|
|
|
=== Emailing the rails security announce list
|
2011-08-16 23:30:29 +00:00
|
|
|
|
2011-08-17 00:39:58 +00:00
|
|
|
Email the security announce list once for each vulnerability fixed.
|
2011-08-04 18:27:26 +00:00
|
|
|
|
|
|
|
You can do this, or ask the security team to do it.
|
|
|
|
|
2011-08-17 00:39:58 +00:00
|
|
|
Email the security reports to:
|
2011-08-04 18:27:26 +00:00
|
|
|
|
2011-08-17 00:39:58 +00:00
|
|
|
* rubyonrails-security@googlegroups.com
|
|
|
|
* linux-distros@vs.openwall.org
|
2011-08-04 18:27:26 +00:00
|
|
|
|
|
|
|
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)
|
|
|
|
|
|
|
|
== 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.
|
2011-11-18 12:05:25 +00:00
|
|
|
|
|
|
|
=== Manually trigger docs generation
|
|
|
|
|
|
|
|
We have a post-receive hook in GitHub that calls the docs server on pushes.
|
2011-11-18 19:22:18 +00:00
|
|
|
It triggers generation and publication of edge docs, updates the contrib app,
|
2011-11-18 12:05:25 +00:00
|
|
|
and generates and publishes stable docs if a new stable tag is detected.
|
|
|
|
|
|
|
|
The hook unfortunately is not invoked by tag pushing, so once the new stable
|
|
|
|
tag has been pushed to origin, please run
|
|
|
|
|
|
|
|
curl -X POST -d '' http://rails-hooks.hashref.com/rails-master-hook
|
|
|
|
|
|
|
|
You should see something like this:
|
|
|
|
|
|
|
|
Rails master hook tasks scheduled:
|
|
|
|
|
|
|
|
* updates the local checkout
|
|
|
|
* updates Rails Contributors
|
|
|
|
* generates and publishes edge docs
|
|
|
|
|
|
|
|
If a new stable tag is detected it also
|
|
|
|
|
|
|
|
* generates and publishes stable docs
|
|
|
|
|
|
|
|
This needs typically a few minutes.
|
|
|
|
|
|
|
|
Note you do not need to specify the tag, the docs server figures it out.
|
|
|
|
|
|
|
|
Also, don't worry if you call that multiple times or the hook is triggered
|
|
|
|
again by some immediate regular push, if the scripts are running new calls
|
|
|
|
are just queued (in a queue of size 1).
|