From eb5aa418c10e5151e0a7e5f425dd8b0c7b78c9c6 Mon Sep 17 00:00:00 2001 From: Rasmus Date: Mon, 3 Jul 2017 11:48:58 +0200 Subject: [PATCH] Update README_maintainer with upstream synchronization instructions * README_maintainer: Update with upstream synchronization instructions. --- README_maintainer | 150 +++++++++++++++++++++--------------------------------- 1 file changed, 58 insertions(+), 92 deletions(-) diff --git a/README_maintainer b/README_maintainer index 6b162aa52..94131d4ce 100644 --- a/README_maintainer +++ b/README_maintainer @@ -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 [[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 *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 [[http://permalink.gmane.org/gmane.emacs.devel/215861][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 +#+end_src +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 [[http://git.savannah.gnu.org/cgit/emacs.git/atom/lisp/org/][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 [[https://git.savannah.gnu.org/cgit/emacs.git][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 [[http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE][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 org-version.inc~ 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. +- =library-of-babel.org= :: 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=. -- 2.11.4.GIT