Usage

For this first phase, I threw everything together into a single file, called simply todo.org. But since I need to configure autodetection of org files anyway, I'll allow for easy future expansion and avoid clutter in my home directory by setting the agenda files to be in a subdirectory, ~/org. The todo.org file will go there.

Each conceptual thing I need to track (I'll go ahead and call these 'items' from here on out) will get a level 1 header. Most, but certainly not all, of the items I need to keep track of correspond to an issue in one of our ticket tracking systems. However, each item might possibly be tracked across more than one ticket in multiple tracking systems, and they almost certainly will have some additional thoughts and context that I want to remember; additionally, they might have artifacts such as pull requests or documents that I will want to reference. It would be good to have these all in one place where I can see them at a glance without having to chase a bunch of links.

If an item is sufficiently simple or not expected to need more than one action, it can be marked with TODO as part of the level 1 header.

* TODO requisition a new laptop

Otherwise, since I expect many items will wind up needing multiple actions over their lifetime, TODO actions will mainly become level 2 headers underneath their items. This will allow me to keep state tracking simple, with only TODO and DONE (and possibly eventually BLOCKED and CANCELED) states needed instead of the many columns that issues get on our project board.

While there are some key bindings around inserting new headlines or TODO entries, I found it simpler this first week to just manually type them out. The exception is if I already have a headline item typed out that I then want to turn into a TODO entry, in which case S-RIGHT will take it into the first state (TODO by default).

Level 1 items will get a short but meaningful title, but also likely some simple notes text immediately below it, including any relevant links. Org-mode headers can get arbitrary amounts of text underneath by indenting at the same level as the title text of the headline.

* Manually gathering analytics from CLI results in a unicode error
  https://issues.redhat.com/browse/AAP-3132
  https://github.com/ansible/tower/issues/5862
  per Phil, only fix in the latest version
** TODO merge if everything is cool
   https://github.com/ansible/awx/pull/12252

It turns out that URLs automatically get treated as links, opening up a new tab in your browser when clicked, without the need to do anything special.

If the size of the notes and links block gets to be more than about half a dozen lines or so, I will probably break it out into one or more level 2 items that can then have their visibility toggled using TAB. Org-mode also supports plain list items by prefixing with a - instead of asterisks, which I'll likely use for these notes.

* Instance Groups fallback / ownership / admin rights
** issues
   Remove fallback behavior when an IG is defined on JT or inventory
   https://github.com/ansible/awx/issues/6134

   Org admin can not operate on instance group associated with their
   org
   https://github.com/ansible/awx/issues/11910

   RFE: Allow assigning an organization IG to a job template without
   requiring org admin
   https://github.com/ansible/awx/issues/4292

   Allow Promptable Instance Group from Predetermined List
   https://github.com/ansible/awx/issues/5711 (mentioned by Bill
   in 6134)
** notes
   - 4292, it seems like what we want is an Org IG Admin role, or make
     the existing Org JT Admin role allow attaching IGs
   - 6134,
     - wants there to be a distinction between fallback and ownership
     - Alan proposed a special Terminate group that would not allow
       any instances to be added, and could be placed in the ordering
       of IGs for an Org such that anything after that point in the
       list doesn't get used for fallback
     - my counter-proposal is to add a boolean field to IGs that
       prevent their use as a fallback
     - we need to capture the opposite problem, of JTs that need a
       special environment not allowing ordinary IGs to be used as
       fallbacks

For now, I'm keeping track of the rough order I'll work on items by raising or lowering their position in the file. Aside from the obvious method of cutting a region and pasting it somewhere else, the method I've been using for this first week has been to place the cursor on the headline and use M-UP and M-DOWN. These key bindings move the entire subtree up or down. There are probably more sophisticated key bindings to manipulate whole subtrees, but I'll worry about that later.

To see an overview of my entire list of TODO actions, I have started to use the global TODO list agenda view. This can be accessed using the key binding C-c a t (assuming you have org-agenda configured the same way I do, as noted in the Settings section below). The downside is that I've been using very simple non-descriptive headers for the direct TODO actions, so it's a bit difficult to meaningfully read the list. I am mitigating this by using the follow-mode (the capital F key binding) while moving around in the TODO list, which causes the upper panel in the window to move to the place in the file where the item your cursor is on actually is. I do wonder, though, if other people do something different to deal with shared context between multiple TODO items.

Finally, I like keeping track of when things happened, so I configured TODO action items to get marked with a CLOSED timestamped property whenever they move into the DONE state (or any future DONE-like states I wind up creating). I'm primarily using S-RIGHT to move into the DONE state.

* ansible-runner streaming with process isolation checks it in every stage
  https://github.com/ansible/ansible-runner/issues/1085
  https://github.com/ansible/ansible-runner/pull/1084 (Hao PR)
** DONE investigate
   CLOSED: [2022-06-01 Wed 10:08]

Settings

In each of the posts in this series, I'll note any changes I've made to my ~/.emacs file to support the new patterns I'm using. I tend to manually edit my config file, but many of these changes can also be made through the Options / Customize Emacs menu.

(setq org-agenda-files   (list "~/org/")
      org-log-done 'time
)

• org-agenda-files: specifies the files and/or directories that will automatically be included in your agenda
• org-log-done: take an action when moving a TODO into a completed state, in this case give it a timestamp

I have also added the key bindings as suggested in the manual:

(global-set-key (kbd "C-c l") #'org-store-link)
(global-set-key (kbd "C-c a") #'org-agenda)
(global-set-key (kbd "C-c c") #'org-capture)

However, I only used the org-agenda binding during this phase, and that only to access the global TODO list.

Key Bindings Learned

I will also briefly note any new key bindings I have started to use in each blog post.

• Structure Editing:
  • M-UP / M-DOWN: move a subtree or item up or down, swapping with the previous or next item as needed
  • M-LEFT / M-RIGHT: decrease or increase the level of the heading
• TODO items:
  • S-LEFT / S-RIGHT: select the next or previous TODO state
• Visibility:
  • TAB: toggle the visibility of the current subtree
  • S-TAB: toggle the visibility of the entire file
• Agenda views:
  • C-c a t: put together and show the global TODO list
    • F: within an agenda view, toggle the ability to follow the TODO list item your cursor is on, showing the full thing in the upper buffer pane
    • q: quit out of an agenda view

Next Steps

Even with only a partial work week for my first week using Org-mode, I filled up my org/todo.org file with more items than was comfortable to look over all at once. I'm definitely going to need to start doing some multi-file organization, especially archiving items that I don't need to consider any more.