Hidden Tasks

[kbknapp]

Description
A way to hide a task from --list output. I'm proposing a task option hidden: bool which hides said task from the output of --list

Alternatives considered

Hard coding a convention such as a leading underscore (i.e. _foo:) being hidden. This has more downsides as it's less clear than hidden: bool.

Additional context

We often had out Toast files to people not familiar with the project they need to build, or even familiar with Toast. For the most part we can get by with just using default tasks, however there are some Toast files where we need to run different target tasks. In these cases users know to use --list to see what options are available. However, many of the tasks shouldn't be used as output targets, and are used as glue tasks. Currently we solve this through convention of a leading underscore (_) means ignore/don't use a task target. We'd prefer being able to hide such tasks from the output of --list entirely.

[kbknapp]

I have a working implementation of this ready for a PR if interested.

[stepchowfun]

Hi @kbknapp, thanks for this feature request. I am not sure how I feel about it. Pros:

• It seems useful.

Cons:

• Toast already has too many features in my opinion. I'm not particularly excited about adding more. The complexity budget is at the limit right now.
• The workarounds like the _underscore convention or simply adding a description that tells the user they probably should run a different task don't seem that terrible to me.
• I am concerned about any feature that could cause the --list output to "lie" by omitting tasks. I can imagine getting bug reports related to this ("why can't I see this task that my coworker told me to run?").

I hope this gives you a sense of how I currently feel about it. For now, I will leave this issue open for further discussion.

[kbknapp]

Understood. Just as counter points for your consideration:

Toast already has too many features in my opinion. I'm not particularly excited about adding more. The complexity budget is at the limit right now.

I sympathize with this! This addition is a relatively small feature with straight forward meaning and doesn't add a new fundamental concept or capability.

The workarounds like the _underscore convention or simply adding a description that tells the user they probably should run a different task don't seem that terrible to me.

For some toastfiles this ins't an issue, but for others it's not as easy. I.e. there is one common toastfile I use that has 20-ish tasks, with two "public" ones. Add to that several of the "private"/"glue" tasks have ENV vars, so the --list command is overwhelmed by information when ideally it would be just two lines.

I am concerned about any feature that could cause the --list output to "lie" by omitting tasks. I can imagine getting bug reports related to this ("why can't I see this task that my coworker told me to run?").

For this I could change the wording of the --list output to say that it's omitting "hidden" ones, or alternatively introduce an --all flag similar to ls which also shows hidden tasks, something like:

$ toast --list
Here are the visible tasks along with their environmental variables (use --all to show hidden tasks):

* foo
* bar

$ toast --list --all
Here are all the tasks along with their environmental variables:

* foo
* bar
* baz
* qux

Granted, that means adding a new flag and a task field, so adding more back to point one 😄

[stepchowfun]

Just to add another idea to the discussion (I'm not sure if I like this or not): only list the tasks that have a non-null description. Then we wouldn't need to introduce any new fields or flags, and it would encourage people to use the description field (for tasks that are meant to be executed directly).

As you suggested, Toast could also print something like "Only tasks which have a description are listed." for clarity on the behavior.

One downside is that you wouldn't be able to add a description for tasks that you don't want to show up in the list. In that case, you could just add # comments in the YAML to explain what those tasks do if needed.

[kbknapp]

Although that would be fine for my use case as well, I think it is less obvious at first glance. i.e. if I open a toastfile and see hidden: true in my (biased) opinion it's less surprising that --list would omit that task. Versus having to run--list and see the message in order to know that tasks with descriptions are displayed, and those without are hidden. Just thinking out loud here too.

[stepchowfun]

My thinking was: for hidden tasks, there is no point in setting the description field (aside from documentation, but a comment would serve that purpose equally well), since it's ignored by Toast; the only thing that field is used for is the --list output. And at the same time, for tasks that are not hidden, it's good to have a description to give meaning to the tasks in the --list output. So there is this 1-to-1 correspondence: hidden tasks should not have a description (since it would just be ignored), and visible tasks should have one. That signals to me that maybe having a description should indicate that a task is meant to be listed, rather than introducing a different mechanism that users would need to manually keep "in sync" with the description per this correspondence, if that makes sense.

[kbknapp]

I totally agree and see where you were coming from, I was just trying to think about it from someone new(ish?) to Toast.

The implementation difference between these two variants is minimal IMO, although hidden tasks does introduce another field to the Task schema which like you've noted adds to the complexity budget.

Thanks for the back and forth with me on the issue! Ultimately, it's your call, and I'm OK either method (and even understand if you'd rather just close the issue for now).

[stepchowfun]

I think one thing that could help with your concern is that we'd update the help text (toast --help) to say something like:

   -l, --list
            Lists the tasks in the toastfile that have a `description`

So a new user would already know what the behavior is as soon as they learn about the --list command for the first time.

[stepchowfun]

(I'd accept a PR for that.)

[stepchowfun]

Fixed by #395.