Merge branch 'maint'
[org-mode.git] / README_maintainer
1 # -*- mode:org -*-
2
3 #+TITLE: Maintainer tasks
4 #+STARTUP: noindent
5
6 This document describes the tasks the Org-mode maintainer has to do
7 and how they are performed.
8
9 * Git workflow
10
11 The git repository has two branches:
12
13 - master :: for current development.
14
15 - maint :: for bug fixes against latest major or minor release.
16
17 Bug fixes always go on =maint= then are merged on =master=.
18
19 New features always go on =master=.
20
21 * Releasing
22
23 ** Major release
24
25 The release number for main releases look like this: =7.13=
26
27 Main releases are made whenever Org is in a state where the feature
28 set is consistent and we feel that the features that are implemented
29 is something we want to support in the future.
30
31 A major release turns the current state of the master branch into a
32 release.
33
34 When doing a /major release/, make sure all changes from the maint
35 branch are merged into the the master branch, then merge the master
36 branch back into maint to synchronize the two.
37
38 ** Minor release
39
40 The release number for minor releases look like this:  =7.13.01=
41
42 Minor releases are small amends to main releases.  Usually they fix
43 critical bugs discovered in a main release.  Minor bugs are usually
44 not fixed -- they will be adressed in the next main release.
45
46 Only the fix to the bug is bundled into a release, without the main
47 development work going on in the master branch.  Since the bug fix
48 will also be needed in the master branch, usually the fix is made in
49 maint then merged in master.
50
51 ** Tagging the release
52
53 When doing a major and a minor release, after all necessary merging
54 is done, tag the _maint_ branch for the release with:
55
56   git tag -a "Adding release tag" release_7.9.1
57
58 and push tags with
59
60   git push --tags
61
62 ** Uploading the release files from the orgmode.org server
63
64 Log on the orgmode.org server as the emacs user and cd to
65 ~/git/org-mode
66
67 From there do
68
69   make release
70   make upload
71
72 to create the .tar.gz and .zip files, the documentation, and to
73 upload everything at the right place.
74
75 * Working with patchwork
76
77 John Wiegley is running a patchwork server that looks at the
78 emacs-orgmode mailing list and extracts patches.  The maintainer and
79 his helpers should work through such patches, give feedback on them
80 and apply the ones which are good and done.  A task for the maintainer
81 is to every now and then try to get old stuff out of that list, by
82 asking some helpers to investigate the patch, by rejecting or
83 accepting it.
84
85 I have found that the best workflow for this is using the pw script by
86 Nate Case, with the modifications for Org-mode made by John Wiegley
87 and Carsten Dominik.  The correct version of this script that should
88 be used with Org mode is distributed in the =mk/= directory of the Org
89 mode distribution.  Here is the basic workflow for this.
90
91 ** Access to the patchwork server
92
93 If you want to work on patchwork patches, you need write access at the
94 patchwork server.  You need to contact John Wiegley to get this
95 access.
96
97 There is a web interface to look at the patches and to change the
98 status of patches.  This interface is self-explanatory.  There is also
99 a command line script which can be very convenient to use.
100
101 ** Testing patches
102
103 To start testing a patch, first assign it to yourself
104
105 : pw update -s "Under Review" -d DELEGATE-NAME NNN
106
107 where =NNN= is a patch number and =DELEGATE-NAME= is your user name on
108 the patchwork server.
109
110 The get the patch into a branch:
111
112 : pw branch NNN
113
114 This will create a local topic branch in your git repository with the
115 name =t/patchNNN=.  You will also be switched to the branch so that
116 you can immediately start testing it.  Quite often small amends need
117 to be made, or documentation has to be added.  Also, many contributors
118 do not yet provide the proper ChangeLog-like entries in the commit
119 message for the patch.  As a maintainer, you have two options here.
120 Either ask the contributor to make the changes and resubmit the patch,
121 or fix it yourself.  In principle, asking to contributor to change the
122 patch until it is complete is the best route, because it will educate
123 the contributor and minimize the work for the maintainer.  However,
124 sometimes it can be less hassle to fix things directly and commit the
125 changes to the same branch =t/patchNNN=.
126
127 If you ask the contributor to make the changes, the patch should be
128 marked on the patchwork server as "changes requested".
129
130 : pw update -s "Changes Requested" -m "What to change" NNN
131
132 This will send an email to the contributor and the mailing list with a
133 request for changes.  The =-m= message should not be more than one
134 sentence and describe the requested changes.  If you need to explain
135 in more detail, write a separate email to the contributor.
136
137 When a new version of the patch arrives, you mark the old one as
138 superseded
139
140 : pw update -s "Superseded" NNN
141
142 and start working at the new one.
143
144 ** Merging a final patch
145
146 Once the patch has been iterated and is final (including the
147 ChangeLog-like entries in the commit message), it should be merged.
148 The assumption here is that the final version of the patch is given by
149 the HEAD state in the branch =t/patchNNN=.  To merge, do this:
150
151 : pw merge -m "maintainer comment" NNN
152
153 This will merge the patch into master, switch back to master and send
154 an email to both contributor and mailing list stating that this change
155 has been accepted, along with the comment given in the =-m= message.
156
157 At some point you might then want to remove the topic branch
158
159 : git branch -d t/patchNNN
160
161 * Synchonization with Emacs
162
163 This is still a significant headache.  Some hand work is needed here.
164
165 Emacs uses bzr.  A useful introduction to bzr for Emacs developers can
166 be found [[http://www.emacswiki.org/emacs/BzrForEmacsDevs][here]].  While I see all the advantages this would have, I
167 cannot bring myself to switch away from git for my day-to-day work,
168 because I know git so well, and because git seems to me as being much
169 more powerful, conceptionally simple (once you have [[http://newartisans.com/2008/04/git-from-the-bottom-up/][bent your head
170 around it]]), and so much faster.
171
172 So the way I have been doing things with Emacs is this:
173
174 1. I do not update the version in Emacs too often.  Just once every
175    few months - this is frequently enough for the Emacs release cycle.
176    Care must be taken to get in a *new and stable* version shortly
177    before Emacs goes into feature freeze and pretest, because that
178    version is going to be in the wild for a long time.
179
180 2. I watch the Emacs diffs for changes made by the maintainers of
181    Emacs in the org-mode files in Emacs.  Any changes that come up
182    there, I merge into the development version of Org-mode.
183    Occasionally I do not do this, if I do not agree with a change.
184    The changes go into Org /without/ a ChangeLog-like entry in the
185    commit message.  The reason for this is that we will later generate
186    a ChangeLog file from our commit messages, and I do not want double
187    ChangeLog entries in the Emacs ChangeLog file.
188
189 3. When I have made a release (usually I wait for the minor releases
190    to stabilize), I *copy* org files into the Emacs repository.  Yes,
191    I do not merge, I copy.  This has been the source of some problems
192    in the past - Emacs developers are not happy when I accidentally
193    overwrite changes they made.  But I have not had the patience to
194    work out a better mechanism, and I really dislike the idea that the
195    version in Emacs starts diverging from my own.
196
197    Careful: Copy /org.texi/ and /orgcard.tex/ into the right places,
198    and also copy the lisp files with *two exceptions*: Do *not* copy
199    /org-colview-xemacs.el/ and /org-loaddefs.el/.  The former does not
200    belong in Emacs.  And the latter would actually be harmful because
201    Emacs generates its own autoloads.
202
203 4. Generate the ChangeLog entries
204
205    For this, I do in the org-mode git repository
206
207    : mk/make_emacs_changelog release_7.02.05..release_7.03.02
208
209    This will spit out ChangeLog entries (for the given commit range)
210    that need to go into the ChangeLog files in Emacs.  Org-mode
211    contributes to 3 different ChangeLog files in Emacs:
212
213    : lisp/org/ChangeLog    (for lisp changes)
214    : doc/misc/ChangeLog    (for org.texi changes)
215    : etc/ChangeLog         (for refcard changes)
216
217    When you run the =make_emacs_changelog= program, you will be
218    prompted for a date in ISO format YYYY-MM-DD, this date will be
219    used in the ChangeLog entries - Emacs developers want these dates
220    to be the time when the change has been installed into Emacs, not
221    the time when we made the change in our own repository.  So all the
222    ChangeLog entries will get the same date.  You will also be
223    prompted for the kind of ChangeLog you want to make, possible
224    answers are =lisp=, =texi=, and =card=.  The program will then
225    select the correct entries for the specified ChangeLog file.  If
226    you don't like being prompted, you can give the date and type as
227    second and third command line arguments to =make_emacs_changelog=,
228    for example
229
230    : mk/make_emacs_changelog release_7.02.05..release_7.03.02 2010-12-11 lisp
231
232    These entries need to be added to the ChangeLog files in Emacs.
233    You should, in the ChangeLog file, select the inserted region of
234    new entries and do =M-x fill-region=, so that the entries are
235    formatted correctly.  I then do look through the entries quickly to
236    make sure they are formatted properly, that the email addresses
237    look right etc.
238
239 5. Commit the changes into the bzr repository and you are done.  Emacs
240    developers often look throught the commit and make minor changes -
241    these need to be merged back into our own repo.
242
243 * Updating the list of hooks/commands/options on Worg
244
245   Load the =mk/eldo.el= file then =M-x eldo-make-doc RET=.
246
247   This will produce an org file with the documentation.
248
249   Import this file into =worg/doc.org=, leaving the header untouched
250   (except for the release number).
251
252   Then commit and push the change on the =worg.git= repository.
253
254 * Copyright assignments
255
256   The maintainer needs to keep track of copyright assignments.  Even
257   better, find a volunteer to do this.
258
259   The list of all contributors from who we have the papers is kept on
260   Worg at http://orgmode.org/worg/org-contribute.php, so that
261   committers can check if a patch can go into the core.
262
263   The assignment process does not allways go smoothly, and it has
264   happened several times that it gets stuck or forgotten at the FSF.
265   The contact at the FSF for this is: copyright-clerk@fsf.org
266
267   Emails from the paper submitter have been ignored in the past, but
268   an email from me (Carsten) as the maintainer of Org mode has usually
269   fixed such cases within a few days.