Support via Liberapay

Org maintenance

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 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 public-inbox of the mailing list at 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 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 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. Major releases have release notes published on https://orgmode.org/Changes.html.
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. Minor releases have release notes published on https://orgmode.org/Changes.html.
Bugfix-only releases
The release number for bugfixes-only releases looks like this: 10.1.1. These releases contain no new feature at all, big or small, and only fix things that we cannot afford not to fix in a minor release. Bugfixes releases don’t have release notes.

Compatibility with Emacs versions

We aim at keeping the latest stable version of Org compatible with the last three major releases of Emacs.

For example, if the latest release of Emacs is 28.x, then you can assume that the latest release of Org is 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 updates.orgmode.org, which uses 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 need to do much more: confirming bugs is a critical contribution.

You can check the Woof! howto if you want to explore the details.

For the release manager and core maintainers

Releasing a new version of Org

Preparing the release

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.

For all releases

Before a minor or major release, all commits in bugfix should be merged into main.

Both minor and major releases are created from the bugfix branch.

Set the ;; Version: [...] metadata in org.el correctly.

For major releases only

When doing a major release (and only then), main is merged back into bugfix.

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:

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 \

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 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 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 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
      Copy to emacs/doc/misc. It may be necessary to replace, @include org-version.inc with @set VERSION 9.0.9 or similar.
      Copy to emacs/etc/refcards. Make sure that \def\orgversionnumber and \def\versionyear are up to date.
    • org-mode/etc
      Copy to emacs/etc/org.
      Copy to emacs/etc/schema.
      Any new entries in this file should be added to emacs/etc/schema/schemas.xml.
      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 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.

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.