Cookbook Best Practices
If we're adopting a cookbook and trying to bring it up to scratch, these are likely the first things people will expect.
We will attempt to support all operating systems releases currently supported by the OS vendor except where there is a compelling reason not to.
Current major operating system support lies in the following:
- Amazon Linux 2
Some cookbooks are not designed to support all of these operating systems. For a full list of supported operating systems please refer to the
kitchen.yml in the cookbook in question
Custom Resources over Attribute Driven
Our cookbooks are application cookbooks, and therefore designed to only manage a single type of application at a time. For example, a PostgreSQL server.
All configurables should be surfaced through a easy to understand, custom resource interface.
For example the postgresql_client_install resource, surfaces a version property. Which is obvious to the user. Much like a template, or file resource.
1postgresql_client_install 'Client install' do 2 version '9.5' 3end
README docuemntation can get very long and hard to navigate. Splitting information down into easily digestable information is crucial in users being able to effectively use the cookbook.
1README.md 2── documentation 3│ ├── resource_apache2_conf.md 4│ ├── resource_apache2_config.md 5│ ├── resource_apache2_default_site.md 6│ ├── resource_apache2_install.md 7│ ├── resource_apache2_mod.md 8│ ├── resource_apache2_module.md 9│ └── resource_apache2_site.md
- The README.md should have links to both resource documents
- The resource documentation should have the following headings:
- resource title
- a table of available properties
- a set of examples using the resource
Our cookbooks follow semver guidelines. See the semver spec for an overview. Semver allows allows cookbook consumers to better understand what version increments mean and plan their testing regiment accordingly