When a Change Needs a Design Proposal
With Chef 16.2 now released, I am auditing all of the various cookbooks across repositories and seeing many inconsistencies that I believe we can and should correct.
Single platform cookbooks:
Method 1:
- cpe_applocker/recipes/default.rb
- calls cpe_applocker resource
- calls uninstall action
- calls configure action
- cpe_adobe_flash/resources/cpe_applocker.rb
- one action_class in the middle of the resource
- two separate actions at the bottom of the resource
resource_name :cpe_applocker
provides :cpe_applocker, :os => 'windows'
default_action :configure
Method 2:
- cpe_dconf/recipes/default.rb
- cpe_dconf/resources/cpe_dconf.rb
- one action block line including name at the top of the resource
resource_name :cpe_dconf
provides :cpe_dconf, :os => 'linux'
default_action :update
Method 3:
- cpe_deprecation_notifier/recipes/default.rb
- calls cpe_deprecation_notifier resource
- cpe_adobe_flash/resources/cpe_applocker.rb
- one action_class at the bottom of the resource
resource_name :cpe_deprecation_notifier
provides :cpe_deprecation_notifier, :os => 'darwin'
default_action :prompt
Multiplatform cookbooks:
Method 1:
- cpe_adobe_flash/recipes/default.rb
- calls single cpe_adobe_flash resource
- cpe_adobe_flash/resources/ACTION_adobe_flash_OS_TYPE.rb
- explicit resource name
- un-explicit provides, explicit os support
- one action block with multiple sub-actions at the bottom of the resource
resource_name :cpe_adobe_flash_darwin
default_action :config
provides :cpe_adobe_flash, :os => 'darwin'
Method 2:
- cpe_chrome/recipes/default.rb
- calls single cpe_chrome resource
- cpe_chrome/resources/cpe_chrome_OS_TYPE.rb
- explicit resource name
- un-explicit provides, explicit os support
- one action block with multiple sub-actions at the top of the resource
resource_name :cpe_adobe_flash_darwin
default_action :config
provides :cpe_adobe_flash, :os => 'darwin'
These are just some of the examples.
there are other method examples that would take me hours to document, but some cookbooks that do not follow any of these models:
- cpe_flatpack
- cpe_gnome_software (not chef 16 compliant)
- cpe_hosts
- cpe_kernel_channel
- cpe_launchd
- cpe_munki (not chef 16 compliant, but I think this is one of the best models for single OS, multiple resource)
- cpe_nomad/cpe_vfuse (resource file name darwin does not match the resource name it provides)
- cpe_pathsd (resources could be combined similarly to cpe_chrome)
- cpe_preferencepanes (resource file name default does not match the resource name it provides)
- cpe_remote (provides line is in a different place than other cookbooks)
- cpe_spotlight (not chef 16 compliant, recipe has strange guards that should likely be put in the resource itself)
- fb_launchd (fail in recipe)
Gusto, Pinterest and Uber's cookbooks have a few other examples of different methods.
Specification
We should come up with some methods and adhere to them - perhaps even co-author linter rules that can enforce these.
I believe we can bring this down to the following:
Single Platform cookbook
- single resource (
foo.rb
with a configure
resource block)
- multiple resources, classified by the responsibility (
configure.rb
install.rb
).
Multi Platform cookbook
- single resource per OS (
macos.rb
, windows.rb
) or unix.rb
if it can handle multiple things (like darwin and ubuntu)
- multiple resources, classified by the responsibility (
configure.rb
install.rb
).
Guards
Guards should either be in the resource or the recipe, but likely not both.
Multiplatform code deduplication
Libraries and/or attribute files should be designed for multi-platform so that code is not repeated across multiple resources. I think this will be the most pertinent/long part of the discussion and we may not be able to agree or come up with a solution for all cases.
To be clear, this is merely a suggestion and I am very open to differing opinions.
Downstream Impact
This should offer no downstream impact other than making it for consistent and creating a model that others can follow when "taking inspiration" from other open source cookbooks.