UP | HOME

Support via Liberapay

Org mode project at FSF40 hackathon

This document describes the task the Org-mode maintainers prepared for FSF40 hackathon. See https://www.fsf.org/events/fsf40-hackathon for terms and conditions, prizes, and rules in general.

Concluding remarks

I did not have any expectations about this hackathon, so just prepared a single task. As it turned out, a number of people showed up, some self-assigning alternative tasks.

In addition to un-archive project, picked up by a team of participants, Kenny Chen worked on improving table alignment code performance, and Pedro Andres Aranda Gutierrez continued his ongoing work on LaTeX export improvements for non-English documents.

The un-archive project itself was worked on by Sam Crawford, Thomas Ingram, David Talmage, Morgan Smith, and Thibaut Meyer. Xiaoduan Chang also tried, although he joined a bit late, and worked independently due to timezone differences.

The team won a prize, becoming one of the three winners of the hackathon. Citing the early announcement during the closing ceremony from memory, they impressed jury for “being especially welcome to the newcomers”.

Shoutout to all the participants who contributed to Org mode and other projects during the hackathon.

P.S. Official announcement from FSF: https://www.fsf.org/blogs/community/2025-hackathon-roundup

Outcomes

un-archive project
https://git.sr.ht/~taingram/org-unarchive/tree/master/item/org-unarchive.el (WIP)
speeding up org-table-align
https://list.orgmode.org/874iqlliik.fsf@mit.edu/T/#u (patches, waiting for copyright assignments)
new features for improved LaTeX export in multi-lingual documents

Timeline

[2025-11-23 Sun 15:23] What is done for un-archive project can be found in https://git.sr.ht/~taingram/org-unarchive/tree/master/item/org-unarchive.el

[2025-11-23 Sun 14:18] Hackathon is ending soon (less than two hours from now, at 10am EST). Please submit your work to the mailing list, even if unfinished. This will give you a chance to participate in the evaluation. (Of course, you are free and ecounraged to continue the work after the hackathon ends.)

[2025-11-23 Sun 12:12] A set of patches for self-assigned project about optimizing org-table-align peformance: https://list.orgmode.org/874iqlliik.fsf@mit.edu/T/#u

[2025-11-22 Sat 14:00] Two patches improving WIP improvements for non-latin Org document export via LaTeX:

[2025-11-22 Sat 09:56] First patch for un-archive project in. https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=68169d17d

[2025-11-21 Fri 19:59] Apart from the project prepared by me for the hackathon, some participants decided to go with others. See the etherpad for more details: https://pad.emacsconf.org/orgmeetup

[2025-11-21 Fri 18:50] For async coordination, you can use Org mailing list. See https://orgmode.org/worg/org-mailing-list.html

[2025-11-21 Fri 17:51] Shared etherpad notes: https://pad.emacsconf.org/orgmeetup (I am re-using the pad for orgmeetup for this hackathon).

[2025-11-21 Fri 17:06] As of now, people are actively brainstorming the task at the Jitsi server. Note that you will not see the full chat history when you join. Ask around to get the message log.

[2025-11-21 Fri] Note that FSF has server issues right now, which affects git repository access. You can find Org code mirror at https://git.sr.ht/~bzg/org-mode [2025-11-22 Sat 11:10] FSF servers are back.

[2025-11-21 Fri] There is FSF’s galenne server where we can screen share and talk by voice. The server is at https://galene.fsf.org/group/hackathon-org-mode/. Username: <any>; Password: JexpAgH9kf. [2025-11-21 Fri 16:22] Let’s use jitsi. It is less confusing. https://meet.jit.si/OrgFSF40hackathon

[2025-11-21 Fri] Also, remember that you can ask questions and coordinate at #org-mode and/or #fsf-hackathon IRC.

Project: New un-archiving functionality for Org mode

This project is about extending functionality of Org mode - a major mode for GNU Emacs and a plain text markup. Org mode can be seen as a combination of Obsidian (or Notion), Jupyter notebooks, LaTeX, classic outliner, task manager, calendar, spreadsheet, and time tracker. See https://orgmode.org/features.html

Org mode is written in Elisp and integrates into common GNU Emacs functionalities. Elisp is extensively documented in https://www.gnu.org/software/emacs/manual/html_node/elisp/, including coding conventions and best practices: https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html In addition, all the necessary information about contributing to Org mode is detailed in https://orgmode.org/worg/org-contribute.html.

For the purposes of this project, you need to understand Org outline markup described in https://orgmode.org/manual/Headlines.html, and how metadata is stored under the heading: https://orgmode.org/manual/Property-Syntax.html.

Your task is to extend the archiving feature of Org mode - moving outlines that are no longer needed: https://orgmode.org/manual/Archiving.html. This feature is very simple - Org mode moves certain headings and their contents into another file (archive file) or under dedicated heading (usually at the end of the document). By default, Org mode also keeps information about the original heading location (see org-archive-save-context-info user option). In Org, a heading is just text, so ‘archive’ means cut here and paste there.

Some users may archive headings by mistake or change their mind after archiving, needing to revert the operation and move the archived headings back to their original location. This can happen either immediately after archiving, or some time (maybe even years) after. Such functionality is currently missing, and it is what I want you to implement during the hackathon.

On the code side, the functions responsible for archiving are org-archive-subtree and org-archive-to-archive-sibling. Please refer to their source code to get an idea about Elisp functions you will need to complete the project. Remember that Emacs has extensive documentation system. You can use C-h f to read a function’s documentation and jump to their definitions. Most of Org mode functions are documented.

The main function you will likely need to work with is org-archive-subtree - this is the function you need to “reverse” to implement un-archiving.

Below, I will provide a tentative task list that will guide you through the project:

  1. [ ] Get familiar with the ideas behind archiving system by reading the manual at https://orgmode.org/manual/Archiving.html.
  2. [ ]

    Get familiar with Org mode archiving:

    • Create a small test.org file with a few headings and subheadings 

      * Heading 1
* Heading 2 :tag:
** Subheading 1 :tag2:
Some text.
** Subheading 2
    • Try archiving different headings using C-c C-x a (or M-x org-archive-subtree)
    • Observe where archived items go (same file, different file, or archive-sibling)
    • Experiment with different settings:
      • Set org-archive-save-context-info to different values and see what information is preserved
      • Try org-archive-default-command to see alternative archiving behaviors
      • Try different org-archive-location

    Start with simple cases before moving to more complex scenarios.

  3. [ ]

    Consult $REPO/lisp/org-archive.el to understand how the archiving works on the code side. Pay attention to user options that can tweak the archiving behavior, especially org-archive-save-context-info. Remember that user options might be modified, which should be taken into account in your code design. You can clone Org mode source code: 

    git clone https://git.sv.gnu.org/git/emacs/org-mode.git
  4. [ ] Implement un-archiving procedure as a new interactive function. You can re-use a lot of code from org-archive-subtree there, adding logic for searching the original location. Start by making un-archiving work for the straightforward case (location unchanged). Corner cases—file moved, heading deleted, or new siblings inserted—can be handled later.
  5. [ ] Once done, implement tests for the new command, checking yourself and ensuring maintainability of your code. Org mode testing system is described in $REPO/testing/README file, and often boils down to simple make test in the git repo. The tests relevant to archiving are all in $REPO/testing/lisp/test-org-archive.el.
  6. [ ] Consider possible user options where un-archiving may be customized. For example, if org-archive-subtree-add-inherited-tags was non-nil when the heading was archived, the archived copy will contain extra tags. Users might want to keep or drop them. The strategy how to handle those tags might (or might not) be something users what to customize.
  7. [ ] If you do come up with such options, make sure to document them in the manual. In any case, do document the new command. The manual is written using Org markup in doc/org-manual.org. Please pay attention to doc/Documentation_Standards.org and otherwise follow by example.
  8. [ ] If you add new options, write relevant tests.
  9. [ ] (optional) Think about un-archiving after org-archive-to-archive-sibling (this function does not save the original context by default). Consider modifying it.
  10. [ ] At the very end, prepare your changes in the form of a patch set, as expected for all contributions. See https://orgmode.org/worg/org-contribute.html#patches

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.