Org mode project at FSF40 hackathon

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