mirror of
https://git.savannah.gnu.org/git/emacs/org-mode.git
synced 2024-09-29 20:07:46 +00:00
Update README_maintainer with upstream synchronization instructions
* README_maintainer: Update with upstream synchronization instructions.
This commit is contained in:
parent
c7bd60833c
commit
eb5aa418c1
|
@ -88,98 +88,64 @@ Org and contributed libraries.
|
||||||
|
|
||||||
org-latest* snapshots are built from the *master* branch.
|
org-latest* snapshots are built from the *master* branch.
|
||||||
|
|
||||||
* Synchronization with Emacs
|
* 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.
|
||||||
|
|
||||||
** Updating etc/ORG-NEWS
|
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.
|
||||||
|
|
||||||
Latest changes in Emacs are described in Emacs =etc/NEWS=, and latest
|
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=
|
||||||
changes in major Emacs packages are described in =etc/ORG-NEWS=.
|
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]].
|
||||||
|
|
||||||
If a major release is meant to be merged with the Emacs trunk (as it
|
Typically, Org can be synchronized by copying over files from the
|
||||||
always should), you need to update Org's =etc/ORG-NEWS= file so that
|
=emacs-sync= branch of the Org repository to the =master= branch of Emacs
|
||||||
you can merge it with that of Emacs. There is one top-level section
|
repository. The =emacs-sync= branch has a few extra changes compared with
|
||||||
for each release that is merged with Emacs.
|
the =maint= branch. If the Emacs maintainers are planning a new release
|
||||||
|
of Emacs soon, it is possible that another branch should be used.
|
||||||
|
|
||||||
** Merging with Emacs trunk branch
|
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 is still a significant headache. Some hand work is needed here.
|
This branch can then be merged with the =master= branch, when everything
|
||||||
|
has been tested.
|
||||||
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.
|
|
||||||
|
|
||||||
|
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
|
* Updating the list of hooks/commands/options on Worg
|
||||||
|
|
||||||
Load the =mk/eldo.el= file then =M-x eldo-make-doc RET=.
|
Load the =mk/eldo.el= file then =M-x eldo-make-doc RET=.
|
||||||
|
|
Loading…
Reference in a new issue