Browse Source

Update README_maintainer with upstream synchronization instructions

* README_maintainer: Update with upstream synchronization
Rasmus 2 years ago
1 changed files with 58 additions and 92 deletions
  1. 58 92

+ 58 - 92

@@ -88,98 +88,64 @@ Org and contributed libraries.
 org-latest* snapshots are built from the *master* branch.
-* Synchronization with Emacs
-** Updating etc/ORG-NEWS
-Latest changes in Emacs are described in Emacs =etc/NEWS=, and latest
-changes in major Emacs packages are described in =etc/ORG-NEWS=. 
-If a major release is meant to be merged with the Emacs trunk (as it
-always should), you need to update Org's =etc/ORG-NEWS= file so that
-you can merge it with that of Emacs.  There is one top-level section
-for each release that is merged with Emacs.
-** Merging with Emacs trunk branch
-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 [[][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 [[][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 *one exception*: Do *not* copy
-   /org-loaddefs.el/, 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.
+* Synchronization Org and upstream Emacs
+Below it is described how Org is kept in sync with the upstream Emacs.
+** Backporting changes from upstream Emacs
+Sometimes Emacs maintainers make changes to Org files.  The process of
+propagating the changes back to the Org repository is called
+/backporting/ for historical reasons.
+To find changes that need to be backported from the Emacs repository,
+the following =git= command, courtesy of [[][Kyle Meyer]], can be used:
+#+begin_src shell
+  git log $rev..origin/emacs-25 -- lisp/org doc/misc/org.texi \
+    etc/refcards/orgcard.tex etc/ORG-NEWS etc/org \
+    etc/schema/od-manifest-schema-v1.2-os.rnc \
+    etc/schema/od-schema-v1.2-os.rnc
+here, =$rev= is the last commit from the =emacs-25= branch that was
+backported.  The should also be done for the =master= branch.
+There is also a [[][feed]] to keep track of new changes in the =lisp/org=
+folder in the Emacs repository.
+** Updating the Org version in upstream Emacs
+New releases of Org should be added to the [[][Emacs repository]].
+Typically, Org can be synchronized by copying over files from the
+=emacs-sync= branch of the Org repository to the =master= branch of Emacs
+repository.  The =emacs-sync= branch has a few extra changes compared with
+the =maint= branch.  If the Emacs maintainers are planning a new release
+of Emacs soon, it is possible that another branch should be used.
+If the new release of Org contains many changes, it may be useful to
+use a separate branch before merging, e.g. =scratch/org-mode-merge=.
+This branch can then be merged with the =master= branch, when everything
+has been tested.
+Please see [[][CONTRIBUTE]] in the Emacs repository for guidelines on
+contributing to the Emacs repository.
+*** Where to files go
+The following list shows where files in Org repository are copied to in
+the Emacs repository, folder by folder.
+**** =org-mode/doc=
+- =org.texi= :: Copy to =emacs/doc/misc=.  It may be necessary to replace,
+                ~@include with ~@set VERSION 9.0.9~ or
+                similar.
+- =orgcard.tex= :: Copy to =emacs/doc/refcards=.  Make sure that
+                   ~\def\orgversionnumber~ and ~\def\versionyear~ are up
+                   to date.
+- :: Copy to =emacs/etc/org=.
+****  =org-mode/etc=
+- =styles/*= :: Copy to =emacs/etc/org=.
+- =schema/*.rnc= :: Copy to =emacs/etc/schema=.
+- =schema/schemas.xml= :: Any new entries in this file should be added
+     to =emacs/etc/schema/schemas.xml=.
+- =ORG-NEWS= :: Copy to =emacs/etc=
+**** =org-mode/lisp=
+- Copy =*.el= files to  =emacs/lisp/org=, except =org-loaddefs.el=!
+- You should create =org-version.el= in =emacs/lisp/org=.  The file is
+  created when you =make= Org.
+**** TODO =org-mode/testing=
 * Updating the list of hooks/commands/options on Worg
   Load the =mk/eldo.el= file then =M-x eldo-make-doc RET=.