Cookbook Versioning Policy

Sane versioning for Chef Cookbooks

This project is maintained by chef-community

Cookbook Versioning Policy v0.1.0


A Chef cookbook is identified by the combination of its name and version, both of which are defined in metadata.rb. After a cookbook has been initially developed and put into use, any changes should be accompanied by an appropriate change to its version when those changes are published. This will allow a correctly working version to be specified with a version constraint in a run_list or environment. The purpose of this document it to define an "appropriate change" to the cookbook's version.

Semantic Versioning

This policy applies the Semantic Versioning Specification to cookbooks. Semantic versioning requires an understanding of the public API of a cookbook, and of what constitutes a backward compatible and non-backward compatible change to that API. This document attempts to provide that understanding.

Public API

The public API of a cookbook consists of anything which, if changed, could break a reasonable use1 of that cookbook. Sometimes this is a judgement call, but it will always include changes to the following:

Most aspects of a cookbook's behavior are also a part of its public API. This is an area where judgement is required; things like bug fixes are not usually considered API changes.

Cookbook Versions

A cookbook's version consists of major, minor, and patch versions. Any change to the cookbook requires a new version when that change is published. The nature of the change determines the new version:

As described in SemVer, when the major or minor version number is incremented the less significant parts of the version should be reset to zero.

For the remainder of this document we will refer to non-backward compatible changes to a cookbook's public API as "major," backward compatible changes to a cookbook's public API as “minor,” and changes with no effect on the public API as "patch."

Changes and their Effect on Version Numbers

The following sections categorize the impact of changes to parts of a cookbook (attributes, recipes, etc.) as major or minor. Keep in mind the following principles:

Changes to Attributes

Major Changes to Attributes

Minor Changes to Attributes


Major Changes to Recipes

Minor Changes to Recipes

Files and Templates

Cookbook files and templates are not part of the public API of a cookbook, unless they are intended to be used from outside the cookbook. So examined in isolation, a change to a cookbook file or template would usually constitute a patch change. However, these changes are often accompanied by changes to the recipe that declares the cookbook_file or template resource, or by changes to attributes used in the template. Examine these changes for potential major or minor version impacts.

Resources and Providers

Major Changes to Resources and Providers

Minor Changes to Resources and Providers


Libraries contain arbitrary Ruby code, so changes to libraries are governed by the same rules of public API compatibility as any other Ruby code. In this section the term “publicly accessible component” refers to any module, class, method, or variable accessible from outside the cookbook. 2

Major Changes to Libraries

Minor Changes to Libraries


Major Changes to Definitions

Minor Changes to Definitions

Miscellaneous Major Version Changes

Miscellaneous Minor Version Changes


1. The "reasonable use" restriction is intended to exclude things like chef-rewind, which effectively turns the entire cookbook into a public API.

2. Ruby does little to enforce separation of API from implementation. As a result, the determination of a library's API becomes a matter of intent. For example, a private method defined in a library class can be called from outside the cookbook by reopening the class. But by defining the method as private, the cookbook intended it not to be part of the API, so a change to the method would only require a patch change to the cookbook's version.