1 files changed, 238 insertions, 0 deletions
diff --git a/RELEASING_RAILS.rdoc b/RELEASING_RAILS.rdoc
new file mode 100644
index 0000000000..9f25adeccc
--- /dev/null
+++ b/RELEASING_RAILS.rdoc
@@ -0,0 +1,238 @@
+= 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.
+
+=== 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.
+
+=== 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
+suits them.
+
+=== 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.
+
+== 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.
+
+=== Are the postgres tests green? If not, make them green
+
+=== 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..
+
+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.
+
+=== Update the RAILS_VERSION file to include the RC.
+
+=== 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.
+
+This will stop you from looking silly when you push an RC to rubygems.org and
+then realise it is broken.
+
+=== 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
+    $ git push
+    $ git push --tags
+    $ 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.
+
+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 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.
+
+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
+* Build and test the gem
+* Release the gems
+* Email security lists
+* Email general announcement lists
+
+=== Emailing the rails 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:
+
+* rubyonrails-security@googlegroups.com
+* linux-distros@vs.openwall.org
+
+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.
+
+=== Manually trigger docs generation
+
+We have a post-receive hook in GitHub that calls the docs server on pushes.
+It triggers generation and publication of edge docs, updates the contrib app,
+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).