summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBastien Guerry <bzg@altern.org>2012-09-03 11:58:06 +0200
committerBastien Guerry <bzg@altern.org>2012-09-03 11:58:06 +0200
commit985e1acb2d6db41fecb985f2bdf48c121315e32a (patch)
treec05e1f485e6d8f6e5039833f54c2ae82516f64c2
parent7efb9cb7ed4782c572a1a630b5b8cb7efa09b553 (diff)
downloadorg-mode-985e1acb2d6db41fecb985f2bdf48c121315e32a.tar.gz
Update the README* files.
-rw-r--r--README29
-rw-r--r--README_DIST25
-rw-r--r--README_contribute (renamed from README_GIT)14
-rw-r--r--README_maintainer166
4 files changed, 119 insertions, 115 deletions
diff --git a/README b/README
index 80c1b01..44b8569 100644
--- a/README
+++ b/README
@@ -10,10 +10,21 @@ README
README_DIST
The README file for the distribution (zip and tar files)
-README_GIT
+README_contribute
Information about the git repository and how to contribute
to Org-mode development.
+README_maintainer
+ Information for the maintainer.
+
+Makefile
+ The makefile to compile and install Org. For installation
+ instructions, see the manual or the more detailed procedure
+ on Worg: http://orgmode.org/worg/dev/org-build-system.html
+
+mk/
+ Files needed for building Org.
+
lisp/
Directory with all the Emacs Lisp files that make up Org.
@@ -21,22 +32,18 @@ doc/
The documentation files. org.texi is the source of the
documentation, org.html and org.pdf are formatted versions of it.
+etc/
+ Files needed for the ODT exporter.
+
contrib/
A directory with third-party additions for Org. Some really cool
stuff is in there.
-ChangeLog
- The standard ChangeLog file.
-
-Makefile
- The makefile to compile and install Org with GNU Make, and also
- for maintenance tasks.
+testing/
+ Testing suite for Org.
request-assign-future.txt
The form that contributors have to sign and get processed with the
FSF before contributed changes can be integrated into the Org
- core. All files in this distribution except the CONTRIB directory
+ core. All files in this distribution except the contrib/ directory
have copyright assigned to the FSF.
-
-EXPERIMENTAL
- Experimental code, not necessarily FSF copyright.
diff --git a/README_DIST b/README_DIST
index c369529..ba5d905 100644
--- a/README_DIST
+++ b/README_DIST
@@ -10,6 +10,11 @@ This distribution contains:
README
This file.
+Makefile
+ The makefile to compile and install Org. For installation
+ instructions, see the manual or the more detailed procedure
+ on Worg: http://orgmode.org/worg/dev/org-build-system.html
+
lisp/
Directory with all the Emacs Lisp files that make up Org.
@@ -21,19 +26,17 @@ contrib/
A directory with third-party additions for Org. Some really cool
stuff is in there.
-ChangeLog
- The standard ChangeLog file, for geeks.
+etc/
+ Files needed for the ODT exporter.
-Changes.org
- An Org-mode file listing the user visible changes in each release.
+mk/
+ Files needed for building Org.
-Makefile
- The makefile to compile and install Org. For installation
- instructions, see the manual.
+testing/
+ Testing suite for Org.
request-assign-future.txt
- The form that contributors have to sign and get processed with the
- FSF before contributed changes can be integrated into the Org
- core. All files in this distribution except the CONTRIB directory
+ The form that contributors have to sign and get processed with
+ the FSF before contributed changes can be integrated into the Org
+ core. All files in this distribution except the contrib/ directory
have copyright assigned to the FSF.
-
diff --git a/README_GIT b/README_contribute
index 2cdb4a9..a73d592 100644
--- a/README_GIT
+++ b/README_contribute
@@ -6,7 +6,6 @@ Emacs mode for organizing your life.
The text below explains the rules for participating in Org-mode
development.
-
* Main rules
1. The master git repository is hosted publicly at orgmode.org.
@@ -27,7 +26,7 @@ development.
3. People who are interested to participate in the Org-mode
development can to so by sending patches to this address:
- emacs-orgmode@gnu.org
+ [[mailto:emacs-orgmode@gnu.org][emacs-orgmode@gnu.org]]
4. An interested developer can also request push access to the
central repository by sending her/his user-info to the
@@ -36,13 +35,13 @@ development.
After you have been added as a user with push privileges,
clone the repository through ssh using
- git clone orgmode@orgmode.org:org-mode.git
+ git clone orgmode@orgmode.org:org-mode.git
By requesting push access, you acknowledge that you have read
and agreed with the following rules:
- - Org-mode is part of Emacs. Therefore, we need to be very
- conscious about changes moving into the Org-mode core.
+ - Org-mode is part of GNU Emacs. Therefore, we need to be
+ very conscious about changes moving into the Org-mode core.
These can originate only from people who have signed the
appropriate papers with the Free Software Foundation. The
files to which this applies are:
@@ -69,7 +68,6 @@ development.
hard to preserve this and I would like to ask everyone to
keep this in mind when developing changes.
-
* The contrib directory
The git repository contains a contrib directory. This directory
@@ -80,12 +78,12 @@ Also non-Lisp extensions like scripts to process Org-mode files
in different ways are welcome in this directory. You should
provide documentation with your extensions, at least in the form
of commentary in the file, better on worg. Please discuss your
-extensions on emacs-orgmode@gnu.org.
+extensions on [[mailto:emacs-orgmode@gnu.org][emacs-orgmode@gnu.org]].
After files have been tested in contrib and found to be generally
useful, we may decide to clarify copyright questions and then
move the file into the Org-mode core. This means they will be
moved up to the root directory and will also eventually be added
-to Emacs bzr repository. The final decision about this rests
+to GNU Emacs bzr repository. The final decision about this rests
with the maintainer.
diff --git a/README_maintainer b/README_maintainer
index 4c31308..f5d99dd 100644
--- a/README_maintainer
+++ b/README_maintainer
@@ -1,11 +1,77 @@
# -*- mode:org -*-
-#+title: Maintainer tasks
-#+startup: noindent
+#+TITLE: 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.01=
+
+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 "Adding release tag" release_7.9.1
+
+and push tags with
+
+ git push --tags
+
+** 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.
+
* Working with patchwork
John Wiegley is running a patchwork server that looks at the
@@ -19,8 +85,8 @@ accepting it.
I have found that the best workflow for this is using the pw script by
Nate Case, with the modifications for Org-mode made by John Wiegley
and Carsten Dominik. The correct version of this script that should
-be used with Org mode is distributed in the =mk/= directory of the
-Org mode distribution. Here is the basic workflow for this.
+be used with Org mode is distributed in the =mk/= directory of the Org
+mode distribution. Here is the basic workflow for this.
** Access to the patchwork server
@@ -92,77 +158,6 @@ At some point you might then want to remove the topic branch
: git branch -d t/patchNNN
-* Releases
-
-** Main releases
-
-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. The release process is a single make command:
-
-: make release TAG=7.13
-
-Before issuing this command, you should make sure that everything
-during the process will work right, you can do so by running
-
-: make testrelease TAG=7.13
-
-When this fails, make sure to clean up. =git reset --hard= if
-necessary, and check if there are unwanted files, directories, or
-branches left over from the testing.
-
-** Minor releases
-
-The release number for minor releases look like this: =7.13.01=
-
-Minor releases are small amends to main releases. Usually they fix
-critical bugs discovered in a main release. Minor bugs are 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 master and
-then cherry-picked into maint. When this is done, a release is made
-from maint with this command:
-
-: make fixrelease TAG=7.13.01
-
-** Updating release files on orgmode.org server
-
-As of 2011-01-15, these directives of the Makefile are meant to be
-used /from orgmode.org server/ and will copy the release files to the
-webserver directory.
-
-- ~$ make makerelease :: creates a =RELEASE/= directory containing
- manuals and release files (=org.tar.gz=, =org.zip=, etc.)
-
-- ~$ make sync_release :: copy the content of =RELEASE/= to the right
- location on the server
-
-- ~$ make sync_manuals :: copy the manuals from =doc/= to the right
- location on the server
-
-- ~$ make relup :: call the three directives described above.
-
-** Between releases
-
-While working on master between releases, I used to use something like
-7.02trans as the version string. I no longer do this. =M-x
-org-version= will spit ut complete version infor related to git, with
-the nearest commit and tag. I you ever need to set a special version
-number, use this:
-
-: mk/set_version 7.02trans
-
-and commit the result. Note that the above command does not change
-the version string in the file from which Org's homepage is generated.
-To change that as well, you would use a =--all= flag. To change only
-this file, use =--only=.
-
* Synchonization with Emacs
This is still a significant headache. Some hand work is needed here.
@@ -249,20 +244,21 @@ So the way I have been doing things with Emacs is this:
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 on Worg
+* 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).
- The file /org-configs/org-hooks.org/ contains a list of all hooks in
- Org. This list has to be updated after hooks have been added or
- removed. The perl script =mk/list-hooks.pl= creates the
- entire section "Hooks and Function variables", including its
- level-one headline. I guess babel code could be used to update this
- automatically, but I have not implemented this - I have been doing
- it by hand every few months.
+ 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.
+ better, find a volunteer to do this.
The list of all contributors from who we have the papers is kept on
Worg at http://orgmode.org/worg/org-contribute.php, so that
@@ -270,7 +266,7 @@ So the way I have been doing things with Emacs is this:
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: copyright-clerk@fsf.org
+ The contact at the FSF for this is: 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