This document describes the tasks the Org-mode maintainers have to do and how they are performed.
Carsten Dominik created Org and is still active on the list.
Bastien Guerry is the current maintainer and release manager. He also hosts orgmode.org on his server.
Ihor Radchenko is maintaining many parts of the code.
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.
A team of Org users is moderating the mailing list.
Some files have a dedicated maintainer: just grep
;; Maintainer in
Org’s repository to find them.
Web presence of maintainers
The recommended way to contact the Org maintainers is by sharing your question, patch or bug report on the mailing list.
Some maintainers have account on websites like github.com, reddit.com, stackoverflow.com, etc. It may be useful sometimes to add them to your conversations. Beware that, if the conversation leads to a bug fix or a change, this will have to be discussed on the mailing list. Here is a table with the accounts of the current maintainers:
What is the role of a maintainer?
You do not need to be an expert of the functionality in the file or to actively improve the file. Just take care of bug reports and feature requests against this file by participating to the discussion on the list.
You are not strictly required to follow the mailing list closely and watch for the relevant emails. When necessary, the relevant messages will be directly forwarded to your email.
As a maintainer, you will need to join the Emacs group on Savannah. When this is done, you will have access to the org-mode.git repository and will be able to push changes without asking for permission first. If your change is a new feature, discuss it on the list first.
In case the change touches files maintained by other maintainers, ask them to review and validate it first. If Org’s maintainer disagrees with a change, he can ask you to revert it.
When possible, please accompany bug fixes and new features with tests. The Org test infrastructure is detailed in testing/README file in the Org repository.
If you are the maintainer of one of the babel language backends, please make sure that the language documentation in WORG is up-to-date.
See also this steps for your first commit as a maintainer.
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. You can support the work of contributors through the Org Mode Liberapay team.
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
What’s in major, minor and bugfix releases?
- Major release
- The release number for a major release look like
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
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. Fixes in these releases are either critical or trivial, for both the core code and the tests.
This is because Org bugfix releases should always be ready to be sync’ed with Emacs development version and we don’t want to worry about adding non-critical and non-trivial changes there when Emacs comes close to a release.
Org releases are compatible with the latest three major Emacs releases
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, you can expect the latest release of Org to be compatible with Emacs 28.x, 27.x and 26.x, but not with Emacs 25.x.
It does not mean that Org will not be usable, at least partially, with older Emacsen: but maintainers are not bound to fix bugs reported on them.
Some Org components also depend on third-party packages available through package archives. Org is only guaranteed to be compatible with the latest stable versions of these third-party packages.
Org versions that are not yet released (from the main or bugfix branch) don’t come with any promise regarding compatibility.
Before any release, maintainers test the release against the last three major releases of Emacs.
Where can I track bugs, patches and updates?
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
Appliedat the beginning of your reply to the patch submitter.
- Bugs reported to the list are not tracked until some confirms them
Confirmedat 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.
Tests for the Org development branch
main branch of Org is tested against the three latest stable
versions of GNU Emacs every three hours, with these rules:
- If the repository didn’t change, don’t rerun the tests.
- If the repository changed, report new test failures to the org-build-failures mailing list.
- If the repository changed and the last test against a specific Emacs version failed, report new failures against the same Emacs version to firstname.lastname@example.org.
For the release manager and core maintainers
Releasing a new version of Org
What goes on the
The git repository has two branches:
main for current development and
bugfix for bug fixes against latest major or minor release.
Critical or trivial bug fixes always go on
bugfix and are merged on
main. Non-trivial and non-critical fixes go on
main. New features
(e.g. new options) always go on
;; Version: header of the
main branch is set to the next stable
release suffixed by
;; Version: header of the
=bugfix branch is set to the last stable release, e.g.
For all releases
bugfix branch should always be merged into
All releases are created from the
Always remember to set the
;; Version: [...] metadata in
For bugfix releases
When doing a bugfix release (and only then), you shoud NOT merge the
main branch into the
For minor and major releases
When doing a minor or major release, the
main branch should be merged
:package-version tags should be added to new and changed
statements as needed. If a statement also contains
:version tag, it
should be removed in favor of
FIXME comments in the code should be reviewed before the release.
They often mark obsolete code to be removed in future releases.
Preparing and annoncing the release
Bugfix releases don’t require specific annoucements.
Minor and major releases should be announced on the mailing list a few weeks in advance so that contributors can test the development branch and report problems.
When the release is done, it is announced on the mailing list.
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 ported from the Emacs repository, look for commits in the Emacs repo that touched Org files since the last sync using the following command:
git log $rev..$target -- lisp/org \ doc/misc/org.org doc/misc/org-setup.org \ etc/ORG-NEWS etc/org etc/refcards/orgcard.tex etc/schema/
$target is the Emacs branch of interest (e.g.,
$rev is the last commit ported from that branch.
There is also a feed to keep track of new changes in the
folder in the Emacs repository.
A log of ported commits is kept at https://git.kyleam.com/orgmode-backport-notes.
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
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
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.
This branch can then be merged with the
master branch, when
everything has been tested.
Please see CONTRIBUTE in the Emacs repository for guidelines on contributing to the Emacs repository.
- Where do files go
The following list shows where files in Org repository are copied to in the Emacs repository, folder by folder.
- Copy to
- Copy to
- Copy to
emacs/etc/refcards. Make sure that
\def\versionyearare up to date.
- Copy to
- Copy to
- Copy to
- Any new entries in this file should be added
- Copy to
- You should create
emacs/lisp/org. The file is created when you
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
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
The maintainers needs to keep track of copyright assignments. Even better, find a volunteer to do this.
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.