#+TITLE:      Org maintenance
#+EMAIL:      bzg at gnu dot org
#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+LANGUAGE:   en
#+PRIORITIES: A C B
#+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:nil -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc ':t
#+HTML_LINK_UP:    index.html
#+HTML_LINK_HOME:  https://orgmode.org/worg/

# This file is released by its authors and contributors under the GNU
# Free Documentation license v1.3 or later, code examples are released
# under the GNU General Public License v3 or later.

This document describes the tasks the Org-mode maintainers have to do
and how they are performed.

* Current maintainers

Carsten Dominik created Org and is still active on the list.

Bastien Guerry is the current maintainer and release manager.

Nicolas Goaziou is maintaining most of the exporters and
[[https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/lisp/org-element.el][org-element.el]], which defines the Org's syntax.

Kyle Meyer is backporting patches made against Org in the Emacs
repository and he updates the Emacs repository with Org latest
releases ; he also hosts the [[https://public-inbox.org/README.html][public-inbox]] of the mailing list at
[[https://list.orgmode.org][list.orgmode.org]].

Timothy (aka "TEC") and Tim Cross are contributor stewards: they make
sure that all contributions get the attention they deserve.

John Corless is helping with confirming reported bugs.

8 people are moderating the mailing list.

Some file have a dedicated maintainer: just grep =;; Maintainer= in
Org's repository to find them.

* What is the role of a maintainer?

If you speak [[https://learnxinyminutes.com/docs/elisp/][Emacs lisp]] and are a regular user of an Org file, please
consider becoming a maintainer for it: you can simply ask on the list.

The maintainer does not need to be an expert of the functionality in
the file or to actively improve the file.  He or she takes care of bug
reports and feature requests against this file by participating to the
discussion on the list.

He can push changes with no permission.  In case the change touches
files maintained by other maintainers, they will need to review and
validate it first.  If Org's maintainer disagrees with a change, he
can ask a maintainer to revert it.

* What's in a release?

** We don't follow a release schedule

Org development is the work of volunteers and we cannot promise to
follow a release schedule.

** We don't use semantic versioning

We use the same numbering convention than semantic versioning, but we
don't follow the rules of SemVer, as expressed in [[https://semver.org][semver.org]].

A /major/ release (e.g. =10=) means: "Hear ye, hear ye!  *All users* should
pay attention and read the release notes before upgrading!".

A /minor/ release (e.g. =10.1=) means: "Hear ye, hear ye!  *Power users and
Org contributors* shoul pay attention and read the release notes before
upgrading!  All other users are welcome to read them too."

This de facto convention has been made explicit after =9.4=.

** Major, minor and bugfix releases

- Major release :: The release number for a major release look like
  this: =10=.  Major releases are made whenever Org is in a state where
  the feature set is consistent and we know that the features that are
  implemented will be supported in the future.

- Minor release :: The release number for minor releases look like
  this: =10.1=.  Minor releases are amends to main releases: small new
  features or bugfixes.

- Bugfix-only releases :: The release number for bugfixes-only
  releases looks like this: =10.1.1=.  These release contain no new
  feature at all, big or small, and only fix things that we cannot
  affort not to fix in a minor release.

** Compatibility with Emacs versions
:PROPERTIES:
:CUSTOM_ID: emacs-compatibility
:END:

We aim at keeping the latest stable version of Org compatible with at
least Emacs =V=, =V-1= and =V-2= - where =V= is the stable major version of
Emacs.

For example, if the current major version of Emacs is 28.x, then the
latest stable version of Org should be compatible with Emacs 28.x,
27.x and 26.x -- but not with Emacs 25.x.

** Conventions before and after Org 9.5

Note that before =Org 9.5=, versions like =9.3=, =9.4=, etc. were
really /major/ ones.  This was confusing for some users, especially
those who expect Org to follow semantic versioning conventions.

* Where can I track bugs, patches and updates?

On [[https://updates.orgmode.org][updates.orgmode.org]], which uses [[https://github.com/bzg/woof][Woof!]] to advertize important
changes (upcoming breaking changes, new releases), confirmed bugs,
submitted patches and help requests.

Here is a super-quick Woof! primer:

- Patches sent to the mailing list are automatically tracked.

- To mark a patch as applied, you just need to place =Applied= at the
  beginning of your reply to the patch submitter.

- Bugs reported to the list are /not/ tracked until some confirms them
  by placing =Confirmed= at the beginning of a line in his reply to the
  bug.

You don't much more: confirming bugs is a critical contribution.

You can check the [[https://github.com/bzg/woof/blob/master/resources/md/howto.org][Woof! howto]] if you want to explore the details.

* For the release manager and core maintainers
** Releasing a new version of Org

*** Git workflow

The git repository has two branches:

- =main= : for current development.
- =bugfix= : for bug fixes against latest major or minor release.

Bug fixes always go on =bugfix= and are merged on =main=.

New features always go on =main=.

*** Major release: merging main into bugfix

All commits in the =bugfix= branch should always be merged into the
=main= branch.  Both minor and major releases are done from the =bugfix=
branch.  When doing a major release, the =main= branch is merged into
the =bugfix= branch.

*** Tagging the release

When doing a major and a minor release, after all necessary merging is
done, tag the _bugfix_ branch for the release with:

  : git tag -a release_9.1.7 -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_9.1.7 -m "Adding release tag"

The GNU ELPA packages is built from the *bugfix* 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 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 =main= 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
=km/emacs-from-master= branch of the Org repository to the =main=
branch of Emacs repository.  The =km/emacs-from-master= branch has a
few extra changes compared with the =bugfix= 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 =main= 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=

**** Update  =emacs/etc/NEWS=

Whenever a new (major) version of Org is synchronized to the Emacs
repository, it should be mentioned in the NEWS file.

** 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 maintainers 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
[[https://orgmode.org/worg/org-contribute.html][this Worg page]], so that committers can check if a patch can go into
the core.

The assignment process does not always 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: =copyright-clerk AT fsf DOT org=

Emails from the paper submitter have been ignored in the past, but an
email from the maintainers of Org mode has usually fixed such cases
within a few days.