UP | HOME

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. He also hosts orgmode.org on his server.

Ihor Radchenko is maintaining many parts of the code.

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:

Name Reddit Stackoverflow GitHub GitLab
Bastien bzg bzg bzg bzg
Ihor yantar92   yantar92  
Timothy tecosaur   tecosaur  

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.

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 should 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.

What’s in 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. 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?

On tracker.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.

Tests for the Org development branch

The 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 bzg@gnu.org.

Tests are run using SourceHut build manifests called from the orgmode.org server. You can get the manifests files from the org-mode-tests repository.

For the release manager and core maintainers

Releasing a new version of Org

What goes on the bugfix and main branches

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 main.

The ;; Version: header of the main branch is set to the next stable release suffixed by -pre: e.g. 9.6-pre. The ;; Version: header of the =bugfix branch is set to the last stable release, e.g. 9.5.5.

For all releases

The bugfix branch should always be merged into main.

All releases are created from the bugfix branch.

Always remember to set the ;; Version: [...] metadata in org.el correctly.

For bugfix releases

When doing a bugfix release (and only then), you should NOT merge the main branch into the bugfix branch.

Security fixes trigger an immediate bugfix release. For other important fixes, we generally wait a week between bugfix releases. Whenever possible for the maintainers, we wait less than two weeks before releasing important fixes.

For minor and major releases

When doing a minor or major release, the main branch should be merged into the bugfix branch. Before the merge, all the changes from Emacs upstream should be ported to bugfix (see Synchronization Org and upstream Emacs).

:package-version tags should be added to new and changed defcustom statements as needed. If a statement also contains :version tag, it should be removed in favor of :package-version.

FIXME comments in the code should be reviewed before the release. They often mark obsolete code to be removed in future releases.

The bugs listed on the bug tracker should be reviewed and possibly acted upon, especially feature regressions. Ideally, the bug tracker should be left with a minimal number of bugs listed.

etc/ORG-NEWS file should be reviewed, and the most impacting changes should be moved closer to the top, so that users can see them first without reading through less impacting changes. The first heading should be changed from Version X.Y (not yet released) to Version X.Y.

Emacs version requirements should be bumped according to the latest Emacs release version minus 2 (see Emacs version support).

The manuals and Changelog pages served at https://orgmode.org and WORG will be automatically updated once the new version lands onto bugfix branch.

At the very end, the new release should be announced on the mailing list, with subject appropriately tagged as announcement on the bug tracker. See an example in https://list.orgmode.org/orgmode/87pmd6p7qs.fsf@gnu.org/. It is also a good idea share the release announcement on major Org mode/Emacs user forums, like /r/orgmode, /r/emacs, and Mastodon.

Releasing by adding a new tag

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

git tag -a release_9.2 -m "Adding release tag"

and push tags with

git push --tags

We also encourage you to sign the release tags like this:

git tag -s release_9.1.7 -m "Adding release tag"

Pushing the new tag will trigger the release on GNU ELPA.

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.

Also, the contents of orgmode.org/Changes.html needs to be updated by copying the first section of etc/ORG-NEWS in the Changes.org page of the orgweb repository.

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/

Here $target is the Emacs branch of interest (e.g., emacs-29), and $rev is the last commit ported from that branch.

There is also a feed to keep track of new changes in the lisp/org 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. scratch/org-mode-merge. 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.

    • org-mode/doc
      org.org
      Copy to emacs/doc/misc.
      org-setup.org
      Copy to emacs/doc/misc.
      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.
      etc/csl/*
      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.

Footnotes:

1

The form is the same with what Emacs CONTRIBUTE file links to, with one answer filled in.

2

The official response time is 5 business days, according https://www.gnu.org/prep/maintain/maintain.html. We allow a bit more.

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.