mirror of
https://git.savannah.gnu.org/git/emacs/org-mode.git
synced 2024-12-27 10:55:04 +00:00
Update the README* files.
This commit is contained in:
Bastien Guerry
parent
7efb9cb7ed
commit
985e1acb2d
29
README
29
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.
|
||||
|
||||
25
README_DIST
25
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.
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
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.
|
||||
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.
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user