README_maintainer

   1 # -*- mode:org -*-
   2
   3 #+TITLE: Org maintainer tasks
   4 #+STARTUP: noindent
   5 #+OPTIONS: ^:nil
   6
   7 This document describes the tasks the Org-mode maintainer has to do
   8 and how they are performed.
   9
  10 * Git workflow
  11
  12 The git repository has two branches:
  13
  14 - master :: for current development.
  15
  16 - maint :: for bug fixes against latest major or minor release.
  17
  18 Bug fixes always go on =maint= then are merged on =master=.
  19
  20 New features always go on =master=.
  21
  22 * Releasing
  23
  24 ** Major release
  25
  26 The release number for main releases look like this: =7.13=
  27
  28 Main releases are made whenever Org is in a state where the feature
  29 set is consistent and we feel that the features that are implemented
  30 is something we want to support in the future.
  31
  32 A major release turns the current state of the master branch into a
  33 release.
  34
  35 When doing a /major release/, make sure all changes from the maint
  36 branch are merged into the the master branch, then merge the master
  37 branch back into maint to synchronize the two.  Further, make sure to
  38 update the Version and Package-Requires headers in org.el.
  39
  40 ** Minor release
  41
  42 The release number for minor releases look like this:  =7.13.1=
  43
  44 Minor releases are small amends to main releases.  Usually they fix
  45 critical bugs discovered in a main release.  Minor bugs are usually
  46 not fixed -- they will be addressed in the next main release.  Make
  47 sure to update the Version header in org.el when making a new minor
  48 release.
  49
  50 Only the fix to the bug is bundled into a release, without the main
  51 development work going on in the master branch.  Since the bug fix
  52 will also be needed in the master branch, usually the fix is made in
  53 maint then merged in master.
  54
  55 ** Tagging the release
  56
  57 When doing a major and a minor release, after all necessary merging is
  58 done, tag the _maint_ branch for the release with:
  59
  60   git tag -a release_7.9.1 -m "Adding release tag"
  61
  62 and push tags with
  63
  64   git push --tags
  65
  66 We also encourage you to sign release tags like this:
  67
  68   git tag -s release_7.9.1 -m "Adding release tag"
  69
  70 ** Uploading the release files from the orgmode.org server
  71
  72 Log on the orgmode.org server as the emacs user and cd to
  73 ~/git/org-mode
  74
  75 From there do
  76
  77   make release
  78   make upload
  79
  80 to create the .tar.gz and .zip files, the documentation, and to
  81 upload everything at the right place.
  82
  83 * Available Org's builds on the server
  84
  85 There are two cron tasks on the server: one that builds the ELPA
  86 packages and one that builds org-latest.tar.gz and org-latest.zip.
  87
  88 ELPA packages are built from the *maint* branch.  One ELPA package
  89 contains Org's core, another one called "org-plus-contrib" contains
  90 Org and contributed libraries.
  91
  92 org-latest* snapshots are built from the *master* branch.
  93
  94 * Synchronization with Emacs
  95
  96 ** Updating etc/ORG-NEWS
  97
  98 Latest changes in Emacs are described in Emacs =etc/NEWS=, and latest
  99 changes in major Emacs packages are described in =etc/ORG-NEWS=.
 100
 101 If a major release is meant to be merged with the Emacs trunk (as it
 102 always should), you need to update Org's =etc/ORG-NEWS= file so that
 103 you can merge it with that of Emacs.  There is one top-level section
 104 for each release that is merged with Emacs.
 105
 106 ** Merging with Emacs trunk branch
 107
 108 This is still a significant headache.  Some hand work is needed here.
 109
 110 Emacs uses bzr.  A useful introduction to bzr for Emacs developers can
 111 be found [[http://www.emacswiki.org/emacs/BzrForEmacsDevs][here]].  While I see all the advantages this would have, I
 112 cannot bring myself to switch away from git for my day-to-day work,
 113 because I know git so well, and because git seems to me as being much
 114 more powerful, conceptionally simple (once you have [[http://newartisans.com/2008/04/git-from-the-bottom-up/][bent your head
 115 around it]]), and so much faster.
 116
 117 So the way I have been doing things with Emacs is this:
 118
 119 1. I do not update the version in Emacs too often.  Just once every
 120    few months - this is frequently enough for the Emacs release cycle.
 121    Care must be taken to get in a *new and stable* version shortly
 122    before Emacs goes into feature freeze and pretest, because that
 123    version is going to be in the wild for a long time.
 124
 125 2. I watch the Emacs diffs for changes made by the maintainers of
 126    Emacs in the org-mode files in Emacs.  Any changes that come up
 127    there, I merge into the development version of Org-mode.
 128    Occasionally I do not do this, if I do not agree with a change.
 129    The changes go into Org /without/ a ChangeLog-like entry in the
 130    commit message.  The reason for this is that we will later generate
 131    a ChangeLog file from our commit messages, and I do not want double
 132    ChangeLog entries in the Emacs ChangeLog file.
 133
 134 3. When I have made a release (usually I wait for the minor releases
 135    to stabilize), I *copy* org files into the Emacs repository.  Yes,
 136    I do not merge, I copy.  This has been the source of some problems
 137    in the past - Emacs developers are not happy when I accidentally
 138    overwrite changes they made.  But I have not had the patience to
 139    work out a better mechanism, and I really dislike the idea that the
 140    version in Emacs starts diverging from my own.
 141
 142    Careful: Copy /org.texi/ and /orgcard.tex/ into the right places,
 143    and also copy the lisp files with *one exception*: Do *not* copy
 144    /org-loaddefs.el/, Emacs generates its own autoloads.
 145
 146 4. Generate the ChangeLog entries
 147
 148    For this, I do in the org-mode git repository
 149
 150    : mk/make_emacs_changelog release_7.02.05..release_7.03.02
 151
 152    This will spit out ChangeLog entries (for the given commit range)
 153    that need to go into the ChangeLog files in Emacs.  Org-mode
 154    contributes to 3 different ChangeLog files in Emacs:
 155
 156    : lisp/org/ChangeLog    (for lisp changes)
 157    : doc/misc/ChangeLog    (for org.texi changes)
 158    : etc/ChangeLog         (for refcard changes)
 159
 160    When you run the =make_emacs_changelog= program, you will be
 161    prompted for a date in ISO format YYYY-MM-DD, this date will be
 162    used in the ChangeLog entries - Emacs developers want these dates
 163    to be the time when the change has been installed into Emacs, not
 164    the time when we made the change in our own repository.  So all the
 165    ChangeLog entries will get the same date.  You will also be
 166    prompted for the kind of ChangeLog you want to make, possible
 167    answers are =lisp=, =texi=, and =card=.  The program will then
 168    select the correct entries for the specified ChangeLog file.  If
 169    you don't like being prompted, you can give the date and type as
 170    second and third command line arguments to =make_emacs_changelog=,
 171    for example
 172
 173    : mk/make_emacs_changelog release_7.02.05..release_7.03.02 2010-12-11 lisp
 174
 175    These entries need to be added to the ChangeLog files in Emacs.
 176    You should, in the ChangeLog file, select the inserted region of
 177    new entries and do =M-x fill-region=, so that the entries are
 178    formatted correctly.  I then do look through the entries quickly to
 179    make sure they are formatted properly, that the email addresses
 180    look right etc.
 181
 182 5. Commit the changes into the bzr repository and you are done.  Emacs
 183    developers often look throught the commit and make minor changes -
 184    these need to be merged back into our own repo.
 185
 186 * Updating the list of hooks/commands/options on Worg
 187
 188   Load the =mk/eldo.el= file then =M-x eldo-make-doc RET=.
 189
 190   This will produce an org file with the documentation.
 191
 192   Import this file into =worg/doc.org=, leaving the header untouched
 193   (except for the release number).
 194
 195   Then commit and push the change on the =worg.git= repository.
 196
 197 * Copyright assignments
 198
 199   The maintainer needs to keep track of copyright assignments.
 200   Even better, find a volunteer to do this.
 201
 202   The assignment form is included in the repository as a file that
 203   you can send to contributors: =request-assign-future.txt=
 204
 205   The list of all contributors from who we have the papers is kept on
 206   Worg at http://orgmode.org/worg/org-contribute.html, so that
 207   committers can check if a patch can go into the core.
 208
 209   The assignment process does not allways go smoothly, and it has
 210   happened several times that it gets stuck or forgotten at the FSF.
 211   The contact at the FSF for this is: mailto:copyright-clerk@fsf.org
 212
 213   Emails from the paper submitter have been ignored in the past, but
 214   an email from me (Carsten) as the maintainer of Org mode has usually
 215   fixed such cases within a few days.