Graph tasks and dependencies

[theunrepentantgeek]

I've found that drawing a graph of tasks and their dependencies is an effective way to understand how a Taskfile is structured, especially if it's a larger file with many tasks.

To date, I've constructed these "by hand", writing a dot file for rendering by GraphViz. This quickly becomes tedious, and I've always stopped as soon as I've learned what I wanted to know.

Would there be interest in a tool that made it easy to generate these diagrams as a form of documentation?

I'm envisaging something that worked like this:

$ task-graph Taskfile.yaml | graphviz -Tpng -o Taskfile.png

I'll probably write this for my own use regardless of this discussion, but I think it'd make a useful contribution to the project.

[pd93]

This has been something on my roadmap for a little while. I did some work a while back to refactor Task to use a DAG for Taskfile inclusion. This is still WIP, but has been delayed because of conflicts with other refactoring/feature work (mainly the work to include remote Taskfiles). Once that code is merged, I intend to pick it up again.

To do this we are using the dominikbraun/graph package which has the ability to generate GraphViz dot files built-in and I intend to add flags to generate this output. I see no reason as to why we cannot extend this functionality beyond Taskfile inclusions to the actual Tasks themselves, but the road to get there is a fairly long one.

I'm curious as a potential future user of this feature how you would design/draw the task graph. For instance, do we include both a task's deps and its child tasks? Do we need a way to distinguish between them? What do we do if a task is called multiple times (see the upcoming looping functionality). Maybe weighted edges?.

Some examples of the diagrams you find useful and why you find them useful would be really insightful. If you do write something I'd be certainly be very interested to see it.

[theunrepentantgeek]

I think you've got a more ambitious take on this than I have!

The concept banging around in my head is a graph that works as an overview of the taskfile, showing which tasks interact with each other and providing a map for what's of interest.

do we include both a task's deps and its child tasks?

I was thinking yes, with different kinds of edges for each link.

do we include both a task's deps and its child tasks?

My first instinct is that no special handling is needed - the graph would already show that a relationship exists between the tasks.

Some examples of the diagrams you find useful and why you find them useful would be really insightful.

Here's a hand generated example, based on the Taskfile for Task itself.

It's not very interesting, because the Taskfile isn't very complex, but it illustrates the concept. Solid links are calls, dashed-links are dependencies.

I'll knock together a sufficient prototype to generate some more complex diagrams.

[theunrepentantgeek]

I had an entertaining weekend working on the prototype. 😁

Here's a graph of the Taskfile.yaml from the Azure Service Operator project - I've already discovered a handful of issues to address, so the graphing exercise has been worth it:

I've pushed my work-in-progress to a branch, I'd be interested in your feedback.