Org maintenance

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.

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.

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.

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.

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.

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.

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.

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.

Maintainers need to keep track of copyright assignments. A list of contributors who have assigned copyright to the FSF is available so that committers can confirm whether a patch can be installed.

New contributors need to submit the form¹ to the FSF.

The assignment process does not always go quickly; occasionally it may get stuck or overlooked at the FSF. If there is no response to the contributor from FSF within a month², the maintainers can ask the contributor to follow up with the FSF, CCing the Org maintainers.

When submitting a change on someone’s behalf, it’s important that the author field of the commit has the correct name and email address of the person who authored the change. This may be done with the --author option:

git commit --author "Arthur D. Author <author@example.com>"

Making sure the author field corresponds to the contributor, and not the committer, helps us track the number of changed lines for contributors without FSF copyright assignment.