Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 237 lines (154 sloc) 7.671 kB
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
1 = Releasing Rails
2
3 In this document, we'll cover the steps necessary to release Rails. Each
4 section contains steps to take during that time before the release. The times
5 suggested in each header are just that: suggestions. However, they should
6 really be considered as minimums.
7
8 == 10 Days before release
9
10 Today is mostly coordination tasks. Here are the things you must do today:
11
12 === Is the CI green? If not, make it green. (See "Fixing the CI")
13
14 Do not release with a Red CI. You can find the CI status here:
15
3cfbee6 @zzak Don't use hash fragment for travis link
zzak authored
16 http://travis-ci.org/rails/rails
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
17
18 === Is Sam Ruby happy? If not, make him happy.
19
20 Sam Ruby keeps a test suite that makes sure the code samples in his book (Agile
21 Web Development with Rails) all work. These are valuable integration tests
22 for Rails. You can check the status of his tests here:
23
24 http://intertwingly.net/projects/dashboard.html
25
26 Do not release with Red AWDwR tests.
27
457b7ff @randomecho proper casing in pronouns; relocate the pro git book [ci skip]
randomecho authored
28 === Do we have any Git dependencies? If so, contact those authors.
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
29
457b7ff @randomecho proper casing in pronouns; relocate the pro git book [ci skip]
randomecho authored
30 Having Git dependencies indicates that we depend on unreleased code.
31 Obviously Rails cannot be released when it depends on unreleased code.
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
32 Contact the authors of those particular gems and work out a release date that
f566fb3 @waynn "suits" is correct here, not "suites"
waynn authored
33 suits them.
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
34
5399b20 @tenderlove moving CI and Sam Ruby to the top of the list. I :heart: CI and Sam
tenderlove authored
35 === Contact the security team (either Koz or tenderlove)
36
37 Let them know of your plans to release. There may be security issues to be
38 addressed, and that can impact your release date.
39
40 === Notify implementors.
41
42 Ruby implementors have high stakes in making sure Rails works. Be kind and
43 give them a heads up that Rails will be released soonish.
44
5342797 @steveklabnik Added extra note about when to email other rubies to RELEASING_RAILS.…
steveklabnik authored
45 This only needs done for major and minor releases, bugfix releases aren't a
46 big enough deal, and are supposed to be backwards compatible.
47
5399b20 @tenderlove moving CI and Sam Ruby to the top of the list. I :heart: CI and Sam
tenderlove authored
48 Send an email just giving a heads up about the upcoming release to these
49 lists:
50
51 * team@jruby.org
52 * community@rubini.us
53 * rubyonrails-core@googlegroups.com
54
55 Implementors will love you and help you.
56
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
57 == 3 Days before release
58
59 This is when you should release the release candidate. Here are your tasks
60 for today:
61
62 === Is the CI green? If not, make it green.
63
64 === Is Sam Ruby happy? If not, make him happy.
65
66 === Contact the security team. CVE emails must be sent on this day.
67
68 === Create a release branch.
69
70 From the stable branch, create a release branch. For example, if you're
71 releasing Rails 3.0.10, do this:
72
73 [aaron@higgins rails (3-0-stable)]$ git checkout -b 3-0-10
74 Switched to a new branch '3-0-10'
75 [aaron@higgins rails (3-0-10)]$
76
77 === Update each CHANGELOG.
78
79 Many times commits are made without the CHANGELOG being updated. You should
80 review the commits since the last release, and fill in any missing information
81 for each CHANGELOG.
82
83 You can review the commits for the 3.0.10 release like this:
84
85 [aaron@higgins rails (3-0-10)]$ git log v3.0.9..
86
c7b8468 @jonleighton Add note about syncing CHANGELOGs
jonleighton authored
87 If you're doing a stable branch release, you should also ensure that all of
88 the CHANGELOG entries in the stable branch are also synced to the master
89 branch.
90
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
91 === Update the RAILS_VERSION file to include the RC.
92
be777b3 @jonleighton Add a note to REALEASING_RAILS about testing the gem locally before r…
jonleighton authored
93 === Build and test the gem.
94
95 Run `rake install` to generate the gems and install them locally. Then try
96 generating a new app and ensure that nothing explodes.
97
6fc2e12 @htanata Some fixes on RELEASING_RAILS.rdoc.
htanata authored
98 This will stop you from looking silly when you push an RC to rubygems.org and
99 then realise it is broken.
be777b3 @jonleighton Add a note to REALEASING_RAILS about testing the gem locally before r…
jonleighton authored
100
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
101 === Release the gem.
102
103 IMPORTANT: Due to YAML parse problems on the rubygems.org server, it is safest
104 to use Ruby 1.8 when releasing.
105
106 Run `rake release`. This will populate the gemspecs with data from
107 RAILS_VERSION, commit the changes, tag it, and push the gems to rubygems.org.
108 Here are the commands that `rake release` should use, so you can understand
109 what to do in case anything goes wrong:
110
111 $ rake all:build
112 $ git commit -am'updating RAILS_VERSION'
092e113 @jeremy Use annotated git tags for release task
jeremy authored
113 $ git tag -m 'v3.0.10.rc1 release' v3.0.10.rc1
5852fcf @spastorino Add git push and git push --tags to RELEASING_RAILS.rdoc
spastorino authored
114 $ git push
115 $ git push --tags
8c36ead @rafaelfranca Fix release instructions
rafaelfranca authored
116 $ for i in $(ls pkg); do gem push $i; done
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
117
118 === Send Rails release announcements
119
120 Write a release announcement that includes the version, changes, and links to
457b7ff @randomecho proper casing in pronouns; relocate the pro git book [ci skip]
randomecho authored
121 GitHub where people can find the specific commit list. Here are the mailing
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
122 lists where you should announce:
123
124 * rubyonrails-core@googlegroups.com
125 * rubyonrails-talk@googlegroups.com
126 * ruby-talk@ruby-lang.org
127
457b7ff @randomecho proper casing in pronouns; relocate the pro git book [ci skip]
randomecho authored
128 Use Markdown format for your announcement. Remember to ask people to report
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
129 issues with the release candidate to the rails-core mailing list.
130
886d011 @tenderlove fixing wrong words. thanks @jbrown
tenderlove authored
131 IMPORTANT: If any users experience regressions when using the release
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
132 candidate, you *must* postpone the release. Bugfix releases *should not*
133 break existing applications.
134
135 === Post the announcement to the Rails blog.
136
457b7ff @randomecho proper casing in pronouns; relocate the pro git book [ci skip]
randomecho authored
137 If you used Markdown format for your email, you can just paste it in to the
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
138 blog.
139
140 * http://weblog.rubyonrails.org
141
457b7ff @randomecho proper casing in pronouns; relocate the pro git book [ci skip]
randomecho authored
142 === Post the announcement to the Rails Twitter account.
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
143
144 == Time between release candidate and actual release
145
457b7ff @randomecho proper casing in pronouns; relocate the pro git book [ci skip]
randomecho authored
146 Check the rails-core mailing list and the GitHub issue list for regressions in
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
147 the RC.
148
149 If any regressions are found, fix the regressions and repeat the release
150 candidate process. We will not release the final until 72 hours after the
151 last release candidate has been pushed. This means that if users find
152 regressions, the scheduled release date must be postponed.
153
154 When you fix the regressions, do not create a new branch. Fix them on the
155 stable branch, then cherry pick the commit to your release branch. No other
156 commits should be added to the release branch besides regression fixing commits.
157
158 == Day of release
159
160 Many of these steps are the same as for the release candidate, so if you need
161 more explanation on a particular step, so the RC steps.
162
22e611e @tenderlove making the order more clear, adding linux distros mailing lists to ou…
tenderlove authored
163 Today, do this stuff in this order:
164
165 * Apply security patches to the release branch
166 * Update CHANGELOG with security fixes.
167 * Update RAILS_VERSION to remove the rc
be777b3 @jonleighton Add a note to REALEASING_RAILS about testing the gem locally before r…
jonleighton authored
168 * Build and test the gem
22e611e @tenderlove making the order more clear, adding linux distros mailing lists to ou…
tenderlove authored
169 * Release the gems
7b03d40 @fxn adds a couple of items to the check list for stable releases [ci skip]
fxn authored
170 * If releasing a new stable version:
171 - Trigger stable docs generation (see below)
172 - Update the version in the home page
22e611e @tenderlove making the order more clear, adding linux distros mailing lists to ou…
tenderlove authored
173 * Email security lists
174 * Email general announcement lists
9d9f591 @tenderlove adding lessons learned so I do not make the same mistake twice
tenderlove authored
175
457b7ff @randomecho proper casing in pronouns; relocate the pro git book [ci skip]
randomecho authored
176 === Emailing the Rails security announce list
9d9f591 @tenderlove adding lessons learned so I do not make the same mistake twice
tenderlove authored
177
22e611e @tenderlove making the order more clear, adding linux distros mailing lists to ou…
tenderlove authored
178 Email the security announce list once for each vulnerability fixed.
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
179
180 You can do this, or ask the security team to do it.
181
22e611e @tenderlove making the order more clear, adding linux distros mailing lists to ou…
tenderlove authored
182 Email the security reports to:
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
183
22e611e @tenderlove making the order more clear, adding linux distros mailing lists to ou…
tenderlove authored
184 * rubyonrails-security@googlegroups.com
00d8ee8 @tenderlove fixing security email address
tenderlove authored
185 * oss-security@lists.openwall.com
6b80917 @tenderlove adding my brain dump of the release process
tenderlove authored
186
187 Be sure to note the security fixes in your announcement along with CVE numbers
188 and links to each patch. Some people may not be able to upgrade right away,
189 so we need to give them the security fixes in patch form.
190
191 * Blog announcements
192 * Twitter announcements
193 * Merge the release branch to the stable branch.
194 * Drink beer (or other cocktail)
195
196 == Misc
197
198 === Fixing the CI
199
200 There are two simple steps for fixing the CI:
201
202 1. Identify the problem
203 2. Fix it
204
205 Repeat these steps until the CI is green.
307fc12 @fxn release instructions: new section about docs generation
fxn authored
206
207 === Manually trigger docs generation
208
209 We have a post-receive hook in GitHub that calls the docs server on pushes.
6fc2e12 @htanata Some fixes on RELEASING_RAILS.rdoc.
htanata authored
210 It triggers generation and publication of edge docs, updates the contrib app,
307fc12 @fxn release instructions: new section about docs generation
fxn authored
211 and generates and publishes stable docs if a new stable tag is detected.
212
213 The hook unfortunately is not invoked by tag pushing, so once the new stable
214 tag has been pushed to origin, please run
215
c2aadf8 @fxn updates the host and port of publish_docs, and changes the release in…
fxn authored
216 rake publish_docs
307fc12 @fxn release instructions: new section about docs generation
fxn authored
217
218 You should see something like this:
219
220 Rails master hook tasks scheduled:
221
222 * updates the local checkout
223 * updates Rails Contributors
224 * generates and publishes edge docs
225
226 If a new stable tag is detected it also
227
228 * generates and publishes stable docs
229
230 This needs typically a few minutes.
231
232 Note you do not need to specify the tag, the docs server figures it out.
233
234 Also, don't worry if you call that multiple times or the hook is triggered
235 again by some immediate regular push, if the scripts are running new calls
236 are just queued (in a queue of size 1).
Something went wrong with that request. Please try again.