191 lines
7.3 KiB
Org Mode
191 lines
7.3 KiB
Org Mode
# -*- mode:org -*-
|
|
|
|
#+TITLE: Org maintainer tasks
|
|
#+STARTUP: noindent
|
|
|
|
This document describes the tasks the Org-mode maintainer has to do
|
|
and how they are performed.
|
|
|
|
* Git workflow
|
|
|
|
The git repository has two branches:
|
|
|
|
- master :: for current development.
|
|
|
|
- maint :: for bug fixes against latest major or minor release.
|
|
|
|
Bug fixes always go on =maint= then are merged on =master=.
|
|
|
|
New features always go on =master=.
|
|
|
|
* Releasing
|
|
|
|
** Major release
|
|
|
|
The release number for main releases look like this: =7.13=
|
|
|
|
Main releases are made whenever Org is in a state where the feature
|
|
set is consistent and we feel that the features that are implemented
|
|
is something we want to support in the future.
|
|
|
|
A major release turns the current state of the master branch into a
|
|
release.
|
|
|
|
When doing a /major release/, make sure all changes from the maint
|
|
branch are merged into the the master branch, then merge the master
|
|
branch back into maint to synchronize the two.
|
|
|
|
** Minor release
|
|
|
|
The release number for minor releases look like this: =7.13.1=
|
|
|
|
Minor releases are small amends to main releases. Usually they fix
|
|
critical bugs discovered in a main release. Minor bugs are usually
|
|
not fixed -- they will be adressed in the next main release.
|
|
|
|
Only the fix to the bug is bundled into a release, without the main
|
|
development work going on in the master branch. Since the bug fix
|
|
will also be needed in the master branch, usually the fix is made in
|
|
maint then merged in master.
|
|
|
|
** Tagging the release
|
|
|
|
When doing a major and a minor release, after all necessary merging is
|
|
done, tag the _maint_ branch for the release with:
|
|
|
|
git tag -a release_7.9.1 -m "Adding release tag"
|
|
|
|
and push tags with
|
|
|
|
git push --tags
|
|
|
|
We also encourage you to sign release tags like this:
|
|
|
|
git tag -s release_7.9.1 -m "Adding release tag"
|
|
|
|
** Uploading the release files from the orgmode.org server
|
|
|
|
Log on the orgmode.org server as the emacs user and cd to
|
|
~/git/org-mode
|
|
|
|
From there do
|
|
|
|
make release
|
|
make upload
|
|
|
|
to create the .tar.gz and .zip files, the documentation, and to
|
|
upload everything at the right place.
|
|
|
|
* Synchonization with Emacs
|
|
|
|
This is still a significant headache. Some hand work is needed here.
|
|
|
|
Emacs uses bzr. A useful introduction to bzr for Emacs developers can
|
|
be found [[http://www.emacswiki.org/emacs/BzrForEmacsDevs][here]]. While I see all the advantages this would have, I
|
|
cannot bring myself to switch away from git for my day-to-day work,
|
|
because I know git so well, and because git seems to me as being much
|
|
more powerful, conceptionally simple (once you have [[http://newartisans.com/2008/04/git-from-the-bottom-up/][bent your head
|
|
around it]]), and so much faster.
|
|
|
|
So the way I have been doing things with Emacs is this:
|
|
|
|
1. I do not update the version in Emacs too often. Just once every
|
|
few months - this is frequently enough for the Emacs release cycle.
|
|
Care must be taken to get in a *new and stable* version shortly
|
|
before Emacs goes into feature freeze and pretest, because that
|
|
version is going to be in the wild for a long time.
|
|
|
|
2. I watch the Emacs diffs for changes made by the maintainers of
|
|
Emacs in the org-mode files in Emacs. Any changes that come up
|
|
there, I merge into the development version of Org-mode.
|
|
Occasionally I do not do this, if I do not agree with a change.
|
|
The changes go into Org /without/ a ChangeLog-like entry in the
|
|
commit message. The reason for this is that we will later generate
|
|
a ChangeLog file from our commit messages, and I do not want double
|
|
ChangeLog entries in the Emacs ChangeLog file.
|
|
|
|
3. When I have made a release (usually I wait for the minor releases
|
|
to stabilize), I *copy* org files into the Emacs repository. Yes,
|
|
I do not merge, I copy. This has been the source of some problems
|
|
in the past - Emacs developers are not happy when I accidentally
|
|
overwrite changes they made. But I have not had the patience to
|
|
work out a better mechanism, and I really dislike the idea that the
|
|
version in Emacs starts diverging from my own.
|
|
|
|
Careful: Copy /org.texi/ and /orgcard.tex/ into the right places,
|
|
and also copy the lisp files with *two exceptions*: Do *not* copy /org-colview-xemacs.el/ and /org-loaddefs.el/. The former does not
|
|
belong in Emacs. And the latter would actually be harmful because
|
|
Emacs generates its own autoloads.
|
|
|
|
4. Generate the ChangeLog entries
|
|
|
|
For this, I do in the org-mode git repository
|
|
|
|
: mk/make_emacs_changelog release_7.02.05..release_7.03.02
|
|
|
|
This will spit out ChangeLog entries (for the given commit range)
|
|
that need to go into the ChangeLog files in Emacs. Org-mode
|
|
contributes to 3 different ChangeLog files in Emacs:
|
|
|
|
: lisp/org/ChangeLog (for lisp changes)
|
|
: doc/misc/ChangeLog (for org.texi changes)
|
|
: etc/ChangeLog (for refcard changes)
|
|
|
|
When you run the =make_emacs_changelog= program, you will be
|
|
prompted for a date in ISO format YYYY-MM-DD, this date will be
|
|
used in the ChangeLog entries - Emacs developers want these dates
|
|
to be the time when the change has been installed into Emacs, not
|
|
the time when we made the change in our own repository. So all the
|
|
ChangeLog entries will get the same date. You will also be
|
|
prompted for the kind of ChangeLog you want to make, possible
|
|
answers are =lisp=, =texi=, and =card=. The program will then
|
|
select the correct entries for the specified ChangeLog file. If
|
|
you don't like being prompted, you can give the date and type as
|
|
second and third command line arguments to =make_emacs_changelog=,
|
|
for example
|
|
|
|
: mk/make_emacs_changelog release_7.02.05..release_7.03.02 2010-12-11 lisp
|
|
|
|
These entries need to be added to the ChangeLog files in Emacs.
|
|
You should, in the ChangeLog file, select the inserted region of
|
|
new entries and do =M-x fill-region=, so that the entries are
|
|
formatted correctly. I then do look through the entries quickly to
|
|
make sure they are formatted properly, that the email addresses
|
|
look right etc.
|
|
|
|
5. Commit the changes into the bzr repository and you are done. Emacs
|
|
developers often look throught the commit and make minor changes -
|
|
these need to be merged back into our own repo.
|
|
|
|
* Updating the list of hooks/commands/options on Worg
|
|
|
|
Load the =mk/eldo.el= file then =M-x eldo-make-doc RET=.
|
|
|
|
This will produce an org file with the documentation.
|
|
|
|
Import this file into =worg/doc.org=, leaving the header untouched
|
|
(except for the release number).
|
|
|
|
Then commit and push the change on the =worg.git= repository.
|
|
|
|
* Copyright assignments
|
|
|
|
The maintainer needs to keep track of copyright assignments.
|
|
Even better, find a volunteer to do this.
|
|
|
|
The assignment form is included in the repository as a file that
|
|
you can send to contributors: =request-assign-future.txt=
|
|
|
|
The list of all contributors from who we have the papers is kept on
|
|
Worg at http://orgmode.org/worg/org-contribute.html, so that
|
|
committers can check if a patch can go into the core.
|
|
|
|
The assignment process does not allways go smoothly, and it has
|
|
happened several times that it gets stuck or forgotten at the FSF.
|
|
The contact at the FSF for this is: mailto:copyright-clerk@fsf.org
|
|
|
|
Emails from the paper submitter have been ignored in the past, but
|
|
an email from me (Carsten) as the maintainer of Org mode has usually
|
|
fixed such cases within a few days.
|