search

ioquatix / bake

An alternative to rake, with all the great stuff and a sprinkling of magic dust.
MIT License
98 stars 6 forks source link

Documentation feedback #8

Open FooBarWidget opened 3 years ago

FooBarWidget commented 3 years ago

This is my impression after reading the documentation:

ioquatix commented 3 years ago

(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 commented 3 years ago

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 commented 3 years ago

(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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

I added experimental support for loading gems. https://github.com/ioquatix/bake/commit/e7f97175df203a4bda3712715356c68512d9d73b