Documentation feedback

[FooBarWidget]

This is my impression after reading the documentation:

• some pages mention @parameter, others @param. Is this intentional?
• some text reference a bakefile, but other text do not seem to want you to make a bakefile, and want you to make a bake.rb instead. It's not clear what the intention is. It comes over to menas if bakefile is a legacy file that shouldn't be used anymore.
• is bake supposed to be a project-local tool, or can (and should) it also be used as a global tool? The comparison with rake makes it seem as if it's only the former. But then the docs mention cases in which you list/execute tasks from an installed gem, or even from http, so that got me confused.

[ioquatix]

(1) Nope, but both are acceptable. I started with @param because it's common. However after creating https://github.com/ioquatix/decode I realised I wanted to avoid abbreviations so reworked this to use @parameter.

(2) A bakefile means bake.rb. I experimented with the different approaches to file naming and decided that it's far easier to have files that end in .rb for Ruby rather than introducing some new "Bakefile" or "bakefile" naming convention. I can rework this terminology as you are right it might be a bit confusing given the historical context.

(3) Right now bake is per-project but I've been experimenting with making it more general. In theory, we can pick up all installed gems and present their commands. However, I'm not really sure if this makes sense generally. What do you think? Probably either defaulting to the local gems or the system gems if not in a project would make sense.

[ioquatix]

For (3), maybe we can introduce bake --gem my_gem command ...

This would execute gem "my_gem" before trying to run the command and also allow for version selection, e.g.

bake --gem "my_gem ~> 1.0" command...

[FooBarWidget]

(3) I don't think that's very valuable. People install gems in order to use them as libraries, or to gain access to CLI commands. Using bake to run tasks in a gem is much like invoking a CLI command provided by a gem — why would they replace their CLI with bake? I can't think of a use case in which running bake on an installed gem is useful.

[FooBarWidget]

Running bake on an http url might be useful, and I'm also struggling to see the use case there. For this to be truly useful, users need to already have bake installed. This means either that bake must already be a widely-deployed tool, or the organization must mandate it to be a pre-installed tool. I can't see that from happening.

The alternative is to download a tarball with an rb file in it, extracting that tarball, and then run the file in it. It's not a one-liner but it's not exactly hard either, and doesn't require the user to install bake first.

[ioquatix]

I'm less concerned about "general users" and more concerned about my own use cases.

Personally, If I can do away with CLIs provided by gems and just use bake, I'd be happy which is why (3) makes some sense to me. I have several projects with CLIs which would potentially be simpler just to use bake directly, even if the command itself is a bit more complex. This is typically for things like frameworks where you want to create a new project, e.g. bake -g utopia utopia:site:create.

The value is that bake provides a really simple and consistent way to handle arguments and commands are more easily discoverable with bake -g utopia list. It also provides a way to compose commands in a single process, which means things like changing log levels, environments, etc trivially compose.

Running bake on an http url might be useful, and I'm also struggling to see the use case there.

I'm not sure if this is something we discussed already? Can you give an example of what you are thinking of?

[ioquatix]

I added experimental support for loading gems. e7f9717