[BUG] Inconsistent behaviour of TODO + COMMENT + TODO dependencies + agenda? [9.5 (9.5-g0a86ad @ /home/ignacio/.emacs.d/elpa/org-9.5/)]

[BUG] Inconsistent behaviour of TODO + COMMENT + TODO dependencies + agenda? [9.5 (9.5-g0a86ad @ /home/ignacio/.emacs.d/elpa/org-9.5/)]

[Ignacio Casso]

Hello,

I'm not sure what is the expected behaviour of the COMMENT keyword for
TODOs and the agenda, since I only found it in the "Exporting" section
of the manual, but I find the following behaviour inconsistent:

- Tasks with a COMMENT keyword or under a heading with a COMMENT keyword
  do not appear in the agenda. I'm not sure if this is a feature or just
  happens because there is a step involving exporting when the agenda is
  constructed, but it seems reasonable to me and I use the COMMENT
  keyword for this sometimes.

- Tasks with a COMMENT keyword or under a heading with a COMMENT keyword
  DO matter when computing dependencies between tasks, when
  org-enforce-todo-dependencies is 't' or there is a 'ORDERED'
  property.

These two points seem inconsistent to me, since the first leads me to
believe that tasks under commented subtrees are as if they did not
exist, but in the second we see that's not true. Am I interpreting the
COMMENT keyword wrong?

Best regards,

Ignacio

P.D: Just when I was going to send this I tried to investigate it a
little bit more to not waste anyone's time, and I found the variable
'org-agenda-skip-comment-trees', which defaults to 't'. So now I see that
if it is set to 'nil' it would not be inconsistent to me anymore, but I
still think that the default behaviour is inconsistent, or at least
unintituive for newcomers, and that maybe a corresponding variable like
'org-dependencies-skip-comment-trees' might be needed.

Emacs  : GNU Emacs 26.3 (build 2, x86_64-pc-linux-gnu, GTK+ Version 3.24.14)
 of 2020-03-26, modified by Debian
Package: Org mode version 9.5 (9.5-g0a86ad @ /home/ignacio/.emacs.d/elpa/org-9.5/)

Re: [BUG] Inconsistent behaviour of TODO + COMMENT + TODO dependencies + agenda? [9.5 (9.5-g0a86ad @ /home/ignacio/.emacs.d/elpa/org-9.5/)]

[Ihor Radchenko]

Ignacio Casso <ignaciocasso@hotmail.com> writes:

Sorry for the late reply.

> I'm not sure what is the expected behaviour of the COMMENT keyword for
> TODOs and the agenda, since I only found it in the "Exporting" section
> of the manual, but I find the following behaviour inconsistent:
>
> - Tasks with a COMMENT keyword or under a heading with a COMMENT keyword
>   do not appear in the agenda. I'm not sure if this is a feature or just
>   happens because there is a step involving exporting when the agenda is
>   constructed, but it seems reasonable to me and I use the COMMENT
>   keyword for this sometimes.

Also, code blocks inside COMMENT subtrees are not considered during code
block execution with noweb.

> - Tasks with a COMMENT keyword or under a heading with a COMMENT keyword
>   DO matter when computing dependencies between tasks, when
>   org-enforce-todo-dependencies is 't' or there is a 'ORDERED'
>   property.
>
> These two points seem inconsistent to me, since the first leads me to
> believe that tasks under commented subtrees are as if they did not
> exist, but in the second we see that's not true. Am I interpreting the
> COMMENT keyword wrong?

There is indeed an inconsistency here.

> P.D: Just when I was going to send this I tried to investigate it a
> little bit more to not waste anyone's time, and I found the variable
> 'org-agenda-skip-comment-trees', which defaults to 't'. So now I see that
> if it is set to 'nil' it would not be inconsistent to me anymore, but I
> still think that the default behaviour is inconsistent, or at least
> unintituive for newcomers, and that maybe a corresponding variable like
> 'org-dependencies-skip-comment-trees' might be needed.

This makes sense. The new variable should default to the old behaviour -
we do not want to break existing Org files relying on it.

Patches are welcome!

Best,
Ihor

Re: [BUG] Inconsistent behaviour of TODO + COMMENT + TODO dependencies + agenda? [9.5 (9.5-g0a86ad @ /home/ignacio/.emacs.d/elpa/org-9.5/)]

[Ignacio Casso]

>> P.D: Just when I was going to send this I tried to investigate it a
>> little bit more to not waste anyone's time, and I found the variable
>> 'org-agenda-skip-comment-trees', which defaults to 't'. So now I see that
>> if it is set to 'nil' it would not be inconsistent to me anymore, but I
>> still think that the default behaviour is inconsistent, or at least
>> unintituive for newcomers, and that maybe a corresponding variable like
>> 'org-dependencies-skip-comment-trees' might be needed.
>
> This makes sense. The new variable should default to the old behaviour -
> we do not want to break existing Org files relying on it.
>
> Patches are welcome!

I was going to write one, but I have found further inconsistencies and
incomplete documentation and I think we should clearly define first how
we want dependencies to behave. According to the Org Mode documentation
and the docstrings of `org-enforce-todo-dependencies' and
`org-block-todo-from-children-or-siblings-or-parent', tasks are blocked
when:

  1. The task has undone children tasks.

  2. A task has a parent with the property :ORDERED:, and there
     are undone sibling tasks prior to the current task

  3. The parent of the task is blocked because it has siblings that should
     be done first, or is child of a blocked grandparent TODO entry."

But they are actually blocked when:

  1. The task has undone DESCENDANT tasks (i.e., undone children of
  children also block)

  2. A task has a parent with the property :ORDERED:, and there
     are sibling tasks prior to the current task which are undone OR
     HAVE UNDONE DESCENDANTS

  3. The parent of the task is blocked because it has siblings that should
     be done first, or is child of a blocked grandparent TODO entry. BUT
     THE TASK IS NOT BLOCKED E.G., IF ITS GRANDPARENT IS BLOCKED AND IS
     PARENT IS DONE OR HAS NO TODO STATE.

So my other issues are:

- Remarks in upper case in points 1 and 2 should be clarified in the
  documentation and docstrings, if that is actually the desired
  behaviour and not a bug. Otherwise, they should be fixed. I can do
  that in the same patch.

- I also find inconsistent that in points 1 and 2 not only parents and
  children are considered for blocking but also further ancestors and
  descendants, but in point three only a direct chain of blocked parents
  is considered.


What do you think about them? I'll start writing the original patch for
now, let me know if you want me to address any of those points too while
I'm at it.

Ignacio

Re: [BUG] Inconsistent behaviour of TODO + COMMENT + TODO dependencies + agenda? [9.5 (9.5-g0a86ad @ /home/ignacio/.emacs.d/elpa/org-9.5/)]

[Ihor Radchenko]

Sorry for the late reply.

Ignacio Casso <ignaciocasso@hotmail.com> writes:

> I was going to write one, but I have found further inconsistencies and
> incomplete documentation and I think we should clearly define first how
> we want dependencies to behave. According to the Org Mode documentation
> and the docstrings of `org-enforce-todo-dependencies' and
> `org-block-todo-from-children-or-siblings-or-parent', tasks are blocked
> when:
>
>   1. The task has undone children tasks.
>
>   2. A task has a parent with the property :ORDERED:, and there
>      are undone sibling tasks prior to the current task
>
>   3. The parent of the task is blocked because it has siblings that should
>      be done first, or is child of a blocked grandparent TODO entry."
>
> But they are actually blocked when:
>
>   1. The task has undone DESCENDANT tasks (i.e., undone children of
>   children also block)
>
>   2. A task has a parent with the property :ORDERED:, and there
>      are sibling tasks prior to the current task which are undone OR
>      HAVE UNDONE DESCENDANTS
>
>   3. The parent of the task is blocked because it has siblings that should
>      be done first, or is child of a blocked grandparent TODO entry. BUT
>      THE TASK IS NOT BLOCKED E.G., IF ITS GRANDPARENT IS BLOCKED AND IS
>      PARENT IS DONE OR HAS NO TODO STATE.

This is indeed inconsistent. I suspect that the main reason is an
omission in the code when a single re-search-forward is used to check if
there are undone descendant tasks. If not and the code deliberately
checks things not mentioned in the manual, we may need to look further
and dig into the mailing list/git logs.

> So my other issues are:
>
> - Remarks in upper case in points 1 and 2 should be clarified in the
>   documentation and docstrings, if that is actually the desired
>   behaviour and not a bug. Otherwise, they should be fixed. I can do
>   that in the same patch.

I think that they are mostly clarified in "5.2.7 TODO dependencies"
section of the manual, except slightly confusing passage about subtasks:

5.2.7 TODO dependencies ::

The structure of Org files—hierarchy and lists—makes it easy to define
TODO dependencies.  Usually, a parent TODO task should not be marked as
done until all TODO subtasks, or children tasks, are marked as done.
                    ^^^^^^^^
Sometimes there is a logical sequence to (sub)tasks, so that one subtask
cannot be acted upon before all siblings above it have been marked as
done.  If you customize the variable ‘org-enforce-todo-dependencies’,
Org blocks entries from changing state to DONE while they have TODO
children that are not DONE.  Furthermore, if an entry has a property
‘ORDERED’, each of its TODO children is blocked until all earlier
siblings are marked as done.  Here is an example:

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92