From mboxrd@z Thu Jan 1 00:00:00 1970 From: Rasmus Subject: Re: Upstream synchronization documentation Date: Tue, 04 Jul 2017 08:50:55 +0200 Message-ID: <87inj8wv8w.fsf@gmx.us> References: <87fuedyfij.fsf@gmx.us> <87a84l8g8l.fsf@kyleam.com> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:43557) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dSHgA-0002Us-QK for emacs-orgmode@gnu.org; Tue, 04 Jul 2017 02:51:24 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dSHg6-00068X-0q for emacs-orgmode@gnu.org; Tue, 04 Jul 2017 02:51:22 -0400 Received: from mout.gmx.net ([212.227.15.15]:54742) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dSHg5-000671-KW for emacs-orgmode@gnu.org; Tue, 04 Jul 2017 02:51:17 -0400 In-Reply-To: <87a84l8g8l.fsf@kyleam.com> (Kyle Meyer's message of "Mon, 03 Jul 2017 15:36:42 -0400") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: kyle@kyleam.com Cc: emacs-orgmode@gnu.org --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hi, Thanks for the comments. > -- 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 That's better. >> +- =3Dorg.texi=3D :: Copy to =3Demacs/doc/misc=3D. It may be necessary = to replace, >> + ~@include org-version.inc~ #+end_src with ~@set VERSION 9.0.9~ > > Leftover "#+end_src" from a previous edit? Yes, indeed. Thanks. >> +** Outdated notes > > Instead of creating this heading, should we just delete the outdated > notes? Deleting is fine by me. I don't know if it is useful to anyone else. Probably not. Rasmus -- =E2=A0=A0=E2=A0=B5 --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=0001-Update-README_maintainer-with-upstream-synchronizati.patch >From 556c2937abc5b3fe0f5b9e8861a30aef748215cc 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 | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 66 insertions(+), 4 deletions(-) diff --git a/README_maintainer b/README_maintainer index 6b162aa52..60821059c 100644 --- a/README_maintainer +++ b/README_maintainer @@ -88,9 +88,71 @@ Org and contributed libraries. org-latest* snapshots are built from the *master* branch. -* Synchronization with Emacs - -** Updating etc/ORG-NEWS +* Synchronization Org and upstream Emacs +Org should be kept in sync with the upstream [[http://git.savannah.gnu.org/cgit/emacs.git/tree/][Emacs repository]]. +Sometimes Org is changed in the Emacs upstream repo. These changes +should be backported. Likewise, new stable releases of Org should be +added to 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 check for changes that needs to be backported from the Emacs +repository, one can use the following =git= command, courtesy of [[http://permalink.gmane.org/gmane.emacs.devel/215861][Kyle +Meyer]], +#+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 +where =$rev= is the last commit from the =emacs-25= branch that was +backported. The should also be done for the =master= branch. + +One may also use Atom feeds to keep track of upstream changes, +e.g. [[http://git.savannah.gnu.org/cgit/emacs.git/atom/lisp/org/][this feed]] show changes to the =lisp/org= folder. +** Updating the Org version in upstream Emacs +After a new release of Org, it should be synced 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 to +the =maint= branch. If the Emacs maintainers are planning a new release +of Emacs soon, it is possible that another branch, e.g. =emacs-25=, +should be used. + +If you are synchronizing a major release of Org, it may be useful to +use a separate branch before merging, e.g. =scratch/org-mode-merge=. +This can then later be merged with the =master= branch, when everything +has been tested. + +Please also see [[http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE][CONTRIBUTE]] in the Emacs repository. +*** Where to files go +The following detail where files in Org repository are copied to in +the Emacs repository. +*** =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, if necessary. +- =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= :: New entries of this files 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= +** Outdated notes +*** 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=. @@ -100,7 +162,7 @@ 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 +*** Merging with Emacs trunk branch This is still a significant headache. Some hand work is needed here. -- 2.13.2 --=-=-=--