Browse Source

Update the README* files.

Bastien Guerry 6 years ago
parent
commit
985e1acb2d
4 changed files with 119 additions and 115 deletions
  1. 18 11
      README
  2. 14 11
      README_DIST
  3. 6 8
      README_GIT
  4. 81 85
      README_maintainer

+ 18 - 11
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.

+ 14 - 11
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 - 8
README_GIT

@@ -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.
 

+ 81 - 85
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