[org] sane default strategies for enforcing `TODO` dependencies

CHANGELOG.develop

@@ -2823,6 +2823,8 @@ files (thanks to Daniel Nicolai)
 - Added =dune= support via =dune-mode= (thanks to Lyman Gillispie)
 - Fixed ocamlformat not properly initialized by following do (thanks to Nicolas Raymond)
 **** Org
+- Provide some sane default strategies for enforcing =TODO= dependencies via
+  =org-todo-dependencies-strategy=. (thanks to Keith Pinson)
 - Load org-mode email integration (mu4e/notmuch) when org is loaded
   (thanks to Steven Allen)
 - Packages:

layers/+emacs/org/README.org

@@ -11,6 +11,7 @@
 - [[#important-note][Important Note]]
 - [[#install][Install]]
   - [[#layer][Layer]]
+  - [[#todo-dependencies][=TODO= dependencies]]
   - [[#agenda-notifications][Agenda notifications]]
   - [[#agenda-recommendations][Agenda recommendations]]
   - [[#github-support][GitHub support]]
@@ -118,6 +119,44 @@ To use this configuration layer: in the main Spacemacs configuration
 file (=~/.spacemacs=), to the existing =dotspacemacs-configuration-layers= list
 add the =org= entry.
 
+** =TODO= dependencies
+
+If you would like to enforce dependencies in your =TODO= hierarchy, this layer has
+some sane default configurations to try via its ~org-todo-dependencies-strategy~
+configuration variable.
+
+Setting it to ~'naive-auto~, will cause an entry to switch to =DONE= when all its
+subentries are done, and to =TODO= otherwise. This does not result in extra
+prompts for the user, but doesn't work well with more workflow states because of
+the literal =DONE= and =TODO=; it is an excellent place for beginners and
+minimalists:
+
+#+BEGIN_SRC emacs-lisp
+  (setq-default dotspacemacs-configuration-layers '(
+    (org :variables
+         org-todo-dependencies-strategy 'naive-auto)))
+#+END_SRC
+
+Setting it to ~'semiauto~, will cause the user to be prompted to change an entry's
+state when the state of the subentries imply it: that is, when they are either
+all done while it is still a todo, or the when they are all still todo's while
+it is done. This assumes next to nothing about your workflow states (it does not
+use literal =TODO= and =DONE=), but may result in additional, possibly surprising,
+prompting for the user; and it has no intelligence to attempt to determine the
+destination state. It is a good thing to try if ~'naive-auto~ does not accomplish
+what you need:
+
+#+BEGIN_SRC emacs-lisp
+  (setq-default dotspacemacs-configuration-layers '(
+    (org :variables
+         org-todo-dependencies-strategy 'naive-auto)))
+#+END_SRC
+
+If neither of these suffice for you, =org-mode= can be configured directly by
+setting ~org-enforce-todo-dependencies~ to ~t~ and writing your own function to
+register on the ~org-after-todo-statistics-hook~. The layer implementation is a
+good reference.
+
 ** Agenda notifications
 To enable notifications for agenda events, set the variable
 =org-enable-notifications= to =t=.
@@ -168,7 +207,7 @@ syntax:
 #+BEGIN_SRC org
   * Friday, 04/02/2021
     ** Appointment 1
-    <2021-04-02 Fri 10:10> 
+    <2021-04-02 Fri 10:10>
     ** TODO Appointment 2
     <2021-04-02 Fri 10:11>
 #+END_SRC

layers/+emacs/org/config.el

@@ -99,6 +99,23 @@ ATTENTION: `valign-mode' will be laggy working with tables contain more than 100
 (defvar org-enable-roam-protocol nil
   "If non-nil, enable org-roam-protocol.
 See https://www.orgroam.com/manual.html#Roam-Protocol.")
-  
+
 (defvar org-enable-asciidoc-support nil
   "If non-nil, enable ox-asciidoc.")
+
+(defvar org-todo-dependencies-strategy nil
+  "The strategy for enforcing dependencies in the TODO hierarchy.
+
+If nil, do nothing; i.e. if dependencies are configured to be enforced
+separately, they will be, otherwise not. If non-nil, set
+`org-enforce-todo-dependencies' to true, and add to the
+`org-after-todo-statistics-hook' as described below.
+
+If `naive-auto', switch the parent entry to DONE when all subentries are done,
+and to TODO otherwise. This does not result in extra prompts for the user, but
+doesn't work well with more workflow states.
+
+If `semiauto', prompt to change entry state when the state of the subentries
+imply it. This assumes next to nothing about your workflow states, but may
+result in additional, possibly surprising, prompting of the user; and it has no
+intelligence to attempt to determine the destination state.")

layers/+emacs/org/funcs.el

@@ -116,3 +116,20 @@ For example: To unfold from a magit diff buffer, evaluate the following:
 (advice-add 'magit-diff-visit-file :after #'spacemacs/org-reveal-advice)"
   (when (derived-mode-p 'org-mode)
     (org-reveal)))
+
+
+;; Based on the suggestion here:
+;; https://orgmode.org/manual/Breaking-Down-Tasks.html
+(defun spacemacs/org-summary-todo-naive-auto (n-done n-not-done)
+  "Switch entry to DONE when all subentries are done, to TODO otherwise."
+  (org-todo (if (= n-not-done 0) "DONE" "TODO")))
+
+(defun spacemacs/org-summary-todo-semiauto (n-done n-not-done)
+  "Prompt to change entry state when the state of the subentries imply it."
+  (and (org-get-todo-state) ;; Don't force a todo state if there is none yet
+       ;; If either it is in a todo state but should be in a done state
+       (if (or (and (org-entry-is-todo-p) (= n-not-done 0))
+               ;; or it is in a done state and should be in a todo state
+               (and (org-entry-is-done-p) (> n-not-done 0)))
+           ;; then prompt to change the state
+           (org-todo))))

layers/+emacs/org/packages.el

@@ -152,6 +152,13 @@
             ;; `helm-org-headings-max-depth'.
             org-imenu-depth 8)
 
+      (when org-todo-dependencies-strategy
+        (setq org-enforce-todo-dependencies t)
+        (add-hook 'org-after-todo-statistics-hook
+                  (case org-todo-dependencies-strategy
+                    (naive-auto #'spacemacs/org-summary-todo-naive-auto)
+                    (semiauto #'spacemacs/org-summary-todo-semiauto))))
+
       (with-eval-after-load 'org-agenda
         (add-to-list 'org-modules 'org-habit))