Configurable templates

[ivey]

As discussed in #437 and #438 there's not currently a way to adjust the templates used to generate the cookbook with berks cookbook and it might be nice to have them.

The proposal to have a git repo containing the template cookbook did not find much love, and neither did the CLI flag for an additional template directory.

We discussed at Triage, and consensus was "more like Rails" but we don't have a better answer than that yet.

This issue is for discussion and ideas, before we try more PRs.

[promisedlandt]

Maybe a hybrid approach would work:

Create a sub directory in the Berkshelf config dir, like ~/.berkshelf/vagrantfile_templates.
Any *.erb file in that directory is a valid option when doing berks cookbook or berks init, with a --vagrantfile flag (so berks cookbook test --vagrantfile debian would use ~/.berkshelf/vagrantfile_templates/debian.erb).
A default vagrantfile can be specified in the config.json - if none is set, use the one currently provided in berkshelf.

These erb files are regular erb templates that get passed the same variables the current Vagrantfile.erb does, only it's all thrown into a mash (no more of this).

Any valid erb file will be accepted, even if it does not use the berkshelf vagrantfile DSL at all, allowing users to basically store a Vagrantfile no more elaborate than the one Berkshelf currently uses.

The berkshelf configuration DSL (however it will look) that allows the user to actually do cool things gets included in the templates as a normal erb expression, starting with a block wrapping the whole Vagrantfile, like so:

<%= # note the equal sign
berkshelf_vagrantfile do |vagrant|
  vagrant.config_name = "box"
%>

# this will be in the generated vagrantfile verbatim
box.ssh.max_tries = 3

<%= 
vagrant.networking do |net|
  net.mode = :private
  net.ip = "33.33.33.12"
end
%>

<% end # closing the berkshelf_vagrantfile block %>

generating, of course:

Vagrant.configure("2") do |box|
  box.ssh.max_tries = 3
  box.vm.network :private_network, ip: "33.33.33.12"
end

This way, a user can use a very simple template if they absolutely want to, or reap the benefits (in our example, something like :private_network getting renamed to :hostonly_network) if they choose to invest their time.

The template will be generated once (on calling berks init or berks cookbook) and will automatically get a comment with the version of the generator, so it can be regenerated with a new berks command, or init.

This isn't quite as powerful as Rails generators, but, honestly, how much power do you need in a DSL that generates another DSL?

[halcyonCorsair]

One important thing for us (which I didn't address in #438) is the ability to add templates which Berkshelf upstream doesn't need to know about.

[sethvargo]

So here's my take:

I would like to provide a DSL that user's can write that is eval-ed and partial-based. What does this mean? Well, the default files remain the same (only to be broken by a major version release). Given a Vagrantfile:

Vagrant.configure("2") do |config|
  # All Vagrant configuration is done here. The most common configuration
  # options are documented and commented below. For a complete reference,
  # please see the online documentation at vagrantup.com.

  # Every Vagrant virtual environment requires a box to build off of.
  config.vm.box = "ubuntu-12.04x64"

  # Enable berkshelf
  config.berkshelf.enabled = true
end

The user can create a template:

Vagrantfile do
  insert_after_line 'config.berkshelf.enabled', 'config.berkshelf.cookbook_path = "~/bar"'
  replace 'config.vm.box', 'config.vm.box = "magic"'
end

And then that same template can define the cookbook "structure":

Cookbook do 
  directory cookbook_name do
    Metadata.insert_at_end 'depends "internal_cookbook"'
  end
end

Basically each "file" is a class that can either be yielded or called as a class method. It will take some time to write the DSL, but the end result will be something very "Chef-like".

[douglaswth]

@sethvargo Would it be possible for this to support other arbitrary templates that aren't already included? For example, CONTRIBUTING.md or TESTING.md which are showing up in cookbooks now.

[sethvargo]

I suppose it could, but I'm no longer actively working on this issue.

[mahmoudimus]

I've taken my own approach here: https://github.com/mahmoudimus/cookiecutter-slim-berkshelf-vagrant

[reset]

I think the right approach is to place templates inside Github repositories and add a command for "installing" templates that would pull from Github and place them in ~/.berkshelf/templates. An update command would also be provided to allow you to update to HEAD or a given hash.

The cookbook command would be modified to allow you to select what template you'd like to generate the cookbook from based on the name of the generator. We would also need to create a type of "template metadata" file which contains at least the name of the generator.

[mahmoudimus]

@reset +1 - I'd be happy to work on this if you want. This seems like a change from your previous comment (#438 (comment)) but with a reasonable compromise.

[reset]

@mahmoudimus yes, I have had time to think about various implementations and I have changed my mind about how they should be distributed and hosted.

If you'd like to pick up the dev work on this that would be awesome!

[sethvargo]

I watched a really interesting demo by @danielsdeleo on the new ChefDK generators. They are using chef-apply and generic Chef recipes to generate Chef cookbooks (it's so meta). If they are good enough for people, it would be nice to remove the generators entirely from Berkshelf.

We already talked about moving the generators to their own projects, but this would really move the generators off our plate entirely.

[reset]

I'm going to close this issue out. The generators were updated in Berkshelf 3.0 to support various patterns and if Chef-DK is able to provide something better we may want to drop them entirely. We'll see.