198 lines
6.4 KiB
Org Mode
198 lines
6.4 KiB
Org Mode
# -*- mode:org -*-
|
|
|
|
#+TITLE: Org maintainer tasks
|
|
#+STARTUP: noindent
|
|
#+OPTIONS: ^:nil
|
|
|
|
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.1=
|
|
|
|
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 release_7.9.1 -m "Adding release tag"
|
|
|
|
and push tags with
|
|
|
|
git push --tags
|
|
|
|
We also encourage you to sign release tags like this:
|
|
|
|
git tag -s release_7.9.1 -m "Adding release tag"
|
|
|
|
** 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.
|
|
|
|
* Available Org's builds on the server
|
|
|
|
There are two cron tasks on the server: one that builds the ELPA
|
|
packages and one that builds org-latest.tar.gz and org-latest.zip.
|
|
|
|
ELPA packages are built from the *maint* branch. One ELPA package
|
|
contains Org's core, another one called "org-plus-contrib" contains
|
|
Org and contributed libraries.
|
|
|
|
org-latest* snapshots are built from the *master* branch.
|
|
|
|
* 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/etc/refcards=. Make sure that ~\def\orgversionnumber~ and ~\def\versionyear~ are up to date.
|
|
|
|
**** =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=.
|
|
|
|
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).
|
|
|
|
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.
|
|
|
|
The assignment form is included in the repository as a file that you
|
|
can send to contributors: =request-assign-future.txt=
|
|
|
|
The list of all contributors from who we have the papers is kept on
|
|
Worg at https://orgmode.org/worg/org-contribute.html, so that
|
|
committers can check if a patch can go into the core.
|
|
|
|
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: mailto: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
|
|
fixed such cases within a few days.
|