ampledata / cookbook-style-guide Goto Github PK

In the "Hints" section theres a recommendation to use global variables. This seems like leading someone down a path of bad habits. In the provided use case the global seems like a bad idea. as it should be driven from an attribute. If one must provide global variables should they not be const with conditional assignment? So that the recipe can be included many times without exception. Even this screams to me of bad form, but maybe more safe/predictable ?

IMHO globals should not be something we offer as an acceptable style.

"Ruby include and Chef require_recipe are always put at the top of a Recipe, just after comments, and before globals and constants."

This is generally common, but may not be bad style. Here's why.

When Chef processes a recipe, it adds the resources it finds to the Resource Collection. When it encounters an "include_recipe", it begins processing that recipe, adding its resources to the Resource Collection. Order matters, and depending on what your cookbook is doing, you may want to reuse another recipe's resources before you continue on.

For example, in (Opscode's nginx::default recipe)[https://github.com/opscode-cookbooks/nginx/blob/master/recipes/default.rb#L33], we do this:

package "nginx"

service "nginx" do 
  action :enable
end

include_recipe "nginx::commons"

service "nginx" do
  action :start
end

There's a couple nuances here, and one may warrant a style guide update :).

We're enabling the service, but not starting it. The "nginx::commons" recipe contains a number of config files and other resources, so we don't want to automatically assume that the service should be started yet. It might be by the package manager, but that's a different story. At the end we make sure that the service is started, so if it were unable to start for some reason, Chef would do the right thing. The "commons" recipe contains resources that are also used by the "nginx::source" recipe, so we want to be able to include those in the right place during the Chef run.

I haven't read the whole guide, so I'm not sure if this is represented, but the placement of a service with action :enable at the top (often after package) and at the bottom with action :start (after the config file resources) is likewise a good practice, based on the ways that distributions decide to manage services with post install package scripts (or not...).

I can open a second issue if that is necessary. Hope this helps, and thank you for starting this project!