Julian's Chef Style Guide
This project contains the Chef Style Guide that I use, and was based on the work we did at SecondMarket. Some of these rules are enforced by FoodCritic; some others are not.
I have a talk entitled "What Makes a Good Cookbook?" based on this material.
Although not strictly a Chef style thing, please always ensure your
user.email are set properly in your
By "properly", I mean that
user.name is your given name (e.g., "Julian Dunn") and
user.email is an actual, working e-mail address for you. It's annoying to see commit log entries from things like "guestuser <login@Bobs-Macbook-Pro.local>".
- Avoid dashes in cookbook names. This is because any LWRPs you create will use the cookbook name as part of the LWRP name, so the methods become very awkward. In particular, since '-' can't be part of a symbol in Ruby, you won't be able to use LWRPs in any cookbooks with '-' in them.
- All organization application cookbooks should be prefixed with a short organizational prefix, such as 'sm' for 'SecondMarket' (e.g. 'smpostgresql')
- Use semantic versioning when numbering cookbooks.
- Only upload stable cookbooks from master.
- Only upload unstable cookbooks from the dev branch. Merge to master and bump the version when stable.
- Always update CHANGELOG.md with any changes, with the JIRA ticket and a brief description.
System and Component Naming
Name things uniformly for their system and component. For the ganglia master,
ganglia/master(if specific to component),
ganglia(if not). For example:
(The foregoing was shamelessly cribbed from Ironfan)
Name attributes after the recipe in which they are primarily used. e.g.
Don't use the default recipe (leave it blank). Instead, create recipes called
client (or other).
Resource Parameter Order
Follow this order for information in each resource declaration:
- Resource ownership
template '/tmp/foobar.txt' do source 'foobar.txt.erb' owner 'someuser' group 'somegroup' mode 00644 variables( :foo => 'bar' ) notifies :reload, 'service[whatever]' action :create end
Always specify all five digits of the file mode, and not as a string.
Always Specify Action
In each resource declarations always specify the action to be taken:
package 'monit' do action :install end
It goes without saying that all cookbooks should pass FoodCritic rules before being uploaded.
$ foodcritic -f all your-cookbook
should return nothing.
Symbols or Strings?
Prefer strings over symbols, because they're easier to read and you don't need to explain to non-Rubyists what a symbol is. Please retrofit old cookbooks as you come across them.
default[:foo][:bar] = 'baz'
default['foo']['bar'] = 'baz'
Use single-quoted strings in all situations where the string doesn't need interpolation.
mixlib-shellout to shell out. Never use backticks, Process.spawn, popen4,
or anything else!
As of Chef Client 12 you can use
directly in recipe DSL.
Constructs to Avoid
normal_attributes- Avoid using attributes at normal precedence since they are set directly on the node object itself, rather than implied (computed) at runtime.
node.set_unless- Can lead to weird behavior if the node object had something set. Avoid unless altogether necessary (one example where it's necessary is in
if node.run_list.include?('foo')i.e. branching in recipes based on what's in the node's run list. Better and more readable to use a feature flag and set its precedence appropriately.
node['foo']['bar']i.e. setting normal attributes without specifying precedence. This is deprecated in Chef 11, so either use
node.set['foo']['bar']to replace its precedence in-place or choose the precedence to suit.
License and Authors
- Author:: Julian C. Dunn (firstname.lastname@example.org)
- Copyright:: 2012-2013, SecondMarket Labs, LLC.
- Copyright:: 2013-2014, Chef Software, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.