Discussion: visibility of template dependencies and args

[canadaduane]

From https://github.com/guybedford/chomp/pull/31#issuecomment-1010201851:

Templates are functions that output a list of tasks, where those tasks in turn can use templates. The jspm template will output the call to the necessary npm template for JSPM to work, with the global option making auto install configurable.

I think what's a bit tricky from a dev standpoint is that there is some "magic" happening inside that is difficult to reason about. What templates depend on what other templates? What args or options are available if I use this template vs. that template?

I'm trying to think of a way to make this easier to see inside. Possibly a chomp command line option that reads the chompfile and lists templates, its dependencies, and the options for all of these? I don't love it, but it's better than trying to find the template sources and learning about internals, I suppose.

Would calling it global-options.npm seem clearer? It can be useful to eg configure a global Babel config this way for all Babel templates to avoid repetition so that’s why I was making sure that connection was clear first and foremost.

I like the goal here, I'm just not sure about how to make invisible things more visible.

[guybedford]

There's a few perspectives here since it's a usability question more than an architecture question, so I would value your feedback on some of the below approaches. Naming is also an important perspective here.

Firstly, I agree it might not be the best way to introduce the global template options. We could still enable auto-install as being set per template with the tempaltes then passing it to the npm template.

Here's one possible naming change turning it into just "options", then introducing auto-install per task first:

[[task]]
  template = "svelte"
  [task.options]
    auto-install = true

Then later on we could introduce the package manager customization as a global option:

[default-options.npm]
  package-manager = 'pnpm'

Finally, we could then later on when a file has lots of auto-install properties, mention that this can also be set as a global npm option:

[default-options.npm]
  package-manager = 'pnpm'
  auto-install = 'npm'

Would the above offer clarify on this at all? I'm not so worried about users understanding the template model. Like you don't need to know all the details of the Rust macro model to use Rust macros most users don't need to know anything about what is happening underneath here.

In terms of the concern about there being invisible stuff going on, large I think the Rust macro arguments do apply - as long as the user knows the effect, it doesn't matter.

Another possibility might be to offer an --eject-templates argument to the CLI that would convert the template invocations into simple tasks removing all the template usages.

For example:

[[task]]
  template = 'npm'
  [task.options]
    package-manager = 'pnpm'
    packages = ["react", "react-dom"]
    auto-install = true

would, when calling chomp --eject-templates, rewrite the chompfile.toml to:

[[task]]
  deps = ["npm:init"]
  run = "pnpm install react react-dom"

[[task]]
  name = "npm:init"
  target = "package.json"
  run = "pnpm init -y"

Another option as you describe could be to have some visualization calls to see the above output as text, say via chomp --show-tasks. Perhaps that might be more flexible in that chomp --show-tasks > chompfile.toml could be the same as an eject.

[guybedford]

The renamings described above have been landed in #35.

[canadaduane]

Another option as you describe could be to have some visualization calls to see the above output as text, say via chomp --show-tasks. Perhaps that might be more flexible in that chomp --show-tasks > chompfile.toml could be the same as an eject.

FWIW I like this last option. If I understand correctly, it "fills in all the blanks" with defaults, thus removing ambiguity and at the same time instructing the user as to what options exist. And doubles as a way to create a "complete" chompfile. Very nice.

[canadaduane]

Another possibility might be to offer an --eject-templates argument to the CLI that would convert the template invocations into simple tasks removing all the template usages.

Thinking on this a little more, I think --eject-templates solves a different problem well, namely allowing a user to tweak templates easily. As a solution to the "what options are available" problem, however, I think it would be too heavy a burden for beginning Chomp users (unless they also happened to need to tweak the templates).

[guybedford]

chomp --eject is now implemented in https://github.com/guybedford/chomp/pull/45. Task visibility via logging is still a feature that can be implemented, but will track that in due course separately.