Cookbook Versioning Policy


#1

My organization has been using chef-solo for about 9 months, and we’re
making the move to chef server. I’m going to need to provide guidance to
cookbook developers on bumping cookbook versions. I plan to follow the
semantic versioning (http://semver.org/) guidelines, where a non-backward
compatible change results in a major version bump, a backward compatible
change results in a minor version bump, and anything else results in a
micro version bump.

I think I can provide guidance on what kind of cookbook changes are
backward compatible and what kinds aren’t, but I imagine some else has
already done that. Are there existing cookbook versioning policy documents
that I could rely on?

Thanks,
Kevin Christen


#2

Hi Kevin,

This is really a great question. In the recent Chef Community Summit,
I raised the topic for discussion, and it seems that everyone agrees
with the SemVer approach, and now we have to do a few things:

  1. Ensure the tools can understand SemVer version strings - from Chef,
    Knife, etc to potentially extending Librarian, Berkshelf, Knife-spork,
    et al.

  2. Define what constitues the amount of change for each level of versioning.

I think the second one might be a good place to start, and
unfortunately I don’t think there’s any documents published yet. I’d
be happy to collaborate with you to come up with some drafts and see
what makes most sense and then we can push it up for community review.

Thoughts?
-Mike Fiedler

On Fri, Nov 16, 2012 at 11:02 PM, Kevin Christen
kevin.christen@gmail.com wrote:

My organization has been using chef-solo for about 9 months, and we’re
making the move to chef server. I’m going to need to provide guidance to
cookbook developers on bumping cookbook versions. I plan to follow the
semantic versioning (http://semver.org/) guidelines, where a non-backward
compatible change results in a major version bump, a backward compatible
change results in a minor version bump, and anything else results in a micro
version bump.

I think I can provide guidance on what kind of cookbook changes are backward
compatible and what kinds aren’t, but I imagine some else has already done
that. Are there existing cookbook versioning policy documents that I could
rely on?

Thanks,
Kevin Christen


#3

Mike,

Let’s do it. I’ll email you offline to coordinate.

Thanks,
Kevin Christen

On Sat, Nov 17, 2012 at 10:23 AM, Mike miketheman@gmail.com wrote:

Hi Kevin,

This is really a great question. In the recent Chef Community Summit,
I raised the topic for discussion, and it seems that everyone agrees
with the SemVer approach, and now we have to do a few things:

  1. Ensure the tools can understand SemVer version strings - from Chef,
    Knife, etc to potentially extending Librarian, Berkshelf, Knife-spork,
    et al.

  2. Define what constitues the amount of change for each level of
    versioning.

I think the second one might be a good place to start, and
unfortunately I don’t think there’s any documents published yet. I’d
be happy to collaborate with you to come up with some drafts and see
what makes most sense and then we can push it up for community review.

Thoughts?
-Mike Fiedler

On Fri, Nov 16, 2012 at 11:02 PM, Kevin Christen
kevin.christen@gmail.com wrote:

My organization has been using chef-solo for about 9 months, and we’re
making the move to chef server. I’m going to need to provide guidance to
cookbook developers on bumping cookbook versions. I plan to follow the
semantic versioning (http://semver.org/) guidelines, where a
non-backward
compatible change results in a major version bump, a backward compatible
change results in a minor version bump, and anything else results in a
micro
version bump.

I think I can provide guidance on what kind of cookbook changes are
backward
compatible and what kinds aren’t, but I imagine some else has already
done
that. Are there existing cookbook versioning policy documents that I
could
rely on?

Thanks,
Kevin Christen


#4

Topic 1 will be a bit of work, since Chef’s Version object currently
doesn’t store the version as a string, and in the brief look I saw of
the postgres schema for Chef 11 at the summit, it looks like it will be
stored there as major, minor, patch. While this will support a minimal
version of the semver spec, it precludes the use of prerelease and build
identifiers. For us, build identifiers are important so that we can
distinguish between upstream and fork versions of community cookbooks.
Build identifiers are also useful when rapidly iterating on a cookbook,
so that you don’t have to bump the version on every commit. I’ve noticed
that when using Berkshelf with a Chef server, it only downloads a new
version of the cookbook if the version has actually changed; uploading
the same version with new content doesn’t work. I personally agree with
this behavior, so I wouldn’t want Jamie to change it:), but it means I
need another piece of versioning information that I can have my build
automation bump that doesn’t have real semantic meaning.

Greg

On 11/17/2012 09:23 AM, Mike wrote:

Hi Kevin,

This is really a great question. In the recent Chef Community Summit,
I raised the topic for discussion, and it seems that everyone agrees
with the SemVer approach, and now we have to do a few things:

  1. Ensure the tools can understand SemVer version strings - from Chef,
    Knife, etc to potentially extending Librarian, Berkshelf, Knife-spork,
    et al.

  2. Define what constitues the amount of change for each level of versioning.

I think the second one might be a good place to start, and
unfortunately I don’t think there’s any documents published yet. I’d
be happy to collaborate with you to come up with some drafts and see
what makes most sense and then we can push it up for community review.

Thoughts?
-Mike Fiedler

On Fri, Nov 16, 2012 at 11:02 PM, Kevin Christen
kevin.christen@gmail.com wrote:

My organization has been using chef-solo for about 9 months, and we’re
making the move to chef server. I’m going to need to provide guidance to
cookbook developers on bumping cookbook versions. I plan to follow the
semantic versioning (http://semver.org/) guidelines, where a non-backward
compatible change results in a major version bump, a backward compatible
change results in a minor version bump, and anything else results in a micro
version bump.

I think I can provide guidance on what kind of cookbook changes are backward
compatible and what kinds aren’t, but I imagine some else has already done
that. Are there existing cookbook versioning policy documents that I could
rely on?

Thanks,
Kevin Christen


#5

+1 for build identifiers

As Greg said, that would finally be a sane ways to differentiate forked
community cookbooks from the upstream ones. As of today, there’s no sane
way of doing this. For sure you could define a different cookbook location
(like “:git => ‘my-fork-of-cookbook-xyz’”) in a Berksfile or Cheffile, but
in the metadata.rb this information is lost again.

There’s a similar discussion ongoing whether to add a url to the
metadata.rb. I believe this is an attempt to solve the same problem, but in
my opinion, adding the url is too much implemtenation detail. If we could
just add something like version 1.0.1.something that uniquely identifies
a forked version then we wouldn’t need something like an url in the
metadata.rb.


#6

On Wed 21 Nov 2012 11:07:26 AM CST, Torben Knerr wrote:

+1 for build identifiers

As Greg said, that would finally be a sane ways to differentiate
forked community cookbooks from the upstream ones. As of today,
there’s no sane way of doing this. For sure you could define a
different cookbook location (like “:git => ‘my-fork-of-cookbook-xyz’”)
in a Berksfile or Cheffile, but in the metadata.rb this information is
lost again.

There’s a similar discussion ongoing whether to add a url to the
metadata.rb. I believe this is an attempt to solve the same problem,
but in my opinion, adding the url is too much implemtenation detail.
If we could just add something like version 1.0.1.something that
uniquely identifies a forked version then we wouldn’t need something
like an url in the metadata.rb.

Exactly. For a more concrete example, our convention (if we could:) is
..+di..,
or something like: 1.0.0+di.1.abcdef. The build number would be
assigned by the build automation, and would not be checked into git,
which is why we add the sha to the build number. This way, we will
never conflict with an upstream metadata.rb, but can still have a
divergent fork. But right now Chef pukes if you give it a version
number that isn’t strictly ...

Greg


#7

While Berkshelf (and Solve) support the latest version of SemVer; it’s important to note that it is a release candidate and not final.

Build numbers were not in the last finalized release (1.0).

Jamie Winsor
@resetexistence

On Nov 21, 2012, at 12:15 PM, Greg Symons gsymons@drillinginfo.com wrote:

On Wed 21 Nov 2012 11:07:26 AM CST, Torben Knerr wrote:

+1 for build identifiers

As Greg said, that would finally be a sane ways to differentiate
forked community cookbooks from the upstream ones. As of today,
there’s no sane way of doing this. For sure you could define a
different cookbook location (like “:git => ‘my-fork-of-cookbook-xyz’”)
in a Berksfile or Cheffile, but in the metadata.rb this information is
lost again.

There’s a similar discussion ongoing whether to add a url to the
metadata.rb. I believe this is an attempt to solve the same problem,
but in my opinion, adding the url is too much implemtenation detail.
If we could just add something like version 1.0.1.something that
uniquely identifies a forked version then we wouldn’t need something
like an url in the metadata.rb.

Exactly. For a more concrete example, our convention (if we could:) is ..+di.., or something like: 1.0.0+di.1.abcdef. The build number would be assigned by the build automation, and would not be checked into git, which is why we add the sha to the build number. This way, we will never conflict with an upstream metadata.rb, but can still have a divergent fork. But right now Chef pukes if you give it a version number that isn’t strictly ...

Greg


#8

That’s a good point, and apparently there’s still a lot of discussion
about build numbers going on1. However, even prerelease identifiers,
which were in the 1.0.0 spec, will make Chef unhappy. My main point
being, we can’t start semverring cookbooks in a way that allows the
differentiation between forks and upstream releases without either
prerelease identifiers (which I don’t particularly like overloading for
this purpose) or build numbers (which make more sense to me as
site-specific portions of the version).

Greg

On Wed 21 Nov 2012 11:39:56 AM CST, Jamie Winsor wrote:

While Berkshelf (and Solve) support the latest version of SemVer; it’s important to note that it is a release candidate and not final.

Build numbers were not in the last finalized release (1.0).

Jamie Winsor
@resetexistence

On Nov 21, 2012, at 12:15 PM, Greg Symons gsymons@drillinginfo.com wrote:

On Wed 21 Nov 2012 11:07:26 AM CST, Torben Knerr wrote:

+1 for build identifiers

As Greg said, that would finally be a sane ways to differentiate
forked community cookbooks from the upstream ones. As of today,
there’s no sane way of doing this. For sure you could define a
different cookbook location (like “:git => ‘my-fork-of-cookbook-xyz’”)
in a Berksfile or Cheffile, but in the metadata.rb this information is
lost again.

There’s a similar discussion ongoing whether to add a url to the
metadata.rb. I believe this is an attempt to solve the same problem,
but in my opinion, adding the url is too much implemtenation detail.
If we could just add something like version 1.0.1.something that
uniquely identifies a forked version then we wouldn’t need something
like an url in the metadata.rb.

Exactly. For a more concrete example, our convention (if we could:) is ..+di.., or something like: 1.0.0+di.1.abcdef. The build number would be assigned by the build automation, and would not be checked into git, which is why we add the sha to the build number. This way, we will never conflict with an upstream metadata.rb, but can still have a divergent fork. But right now Chef pukes if you give it a version number that isn’t strictly ...

Greg


#9

Now that Cookbook Versioning Policy v0.1.0 is out (
https://github.com/chef-community/cvp), it’s a good time to revisit this
discussion.

Do you still need prerelease identifiers or build numbers for cookbooks?

The limitation of the current versioning scheme to be strictly “
..” is still one of the pain points for me.

Created CHEF-4027 to bring up the discussion again:
http://tickets.opscode.com/browse/CHEF-4027

Cheers,
Torben

On Wed, Nov 21, 2012 at 7:33 PM, Greg Symons gsymons@drillinginfo.comwrote:

That’s a good point, and apparently there’s still a lot of discussion
about build numbers going on1. However, even prerelease identifiers,
which were in the 1.0.0 spec, will make Chef unhappy. My main point
being, we can’t start semverring cookbooks in a way that allows the
differentiation between forks and upstream releases without either
prerelease identifiers (which I don’t particularly like overloading for
this purpose) or build numbers (which make more sense to me as
site-specific portions of the version).

Greg

On Wed 21 Nov 2012 11:39:56 AM CST, Jamie Winsor wrote:

While Berkshelf (and Solve) support the latest version of SemVer; it’s
important to note that it is a release candidate and not final.

Build numbers were not in the last finalized release (1.0).

Jamie Winsor
@resetexistence

On Nov 21, 2012, at 12:15 PM, Greg Symons gsymons@drillinginfo.com
wrote:

On Wed 21 Nov 2012 11:07:26 AM CST, Torben Knerr wrote:

+1 for build identifiers

As Greg said, that would finally be a sane ways to differentiate
forked community cookbooks from the upstream ones. As of today,
there’s no sane way of doing this. For sure you could define a
different cookbook location (like “:git => ‘my-fork-of-cookbook-xyz’”)
in a Berksfile or Cheffile, but in the metadata.rb this information is
lost again.

There’s a similar discussion ongoing whether to add a url to the
metadata.rb. I believe this is an attempt to solve the same problem,
but in my opinion, adding the url is too much implemtenation detail.
If we could just add something like version 1.0.1.something that
uniquely identifies a forked version then we wouldn’t need something
like an url in the metadata.rb.

Exactly. For a more concrete example, our convention (if we could:) is
.<upstream-**minor>.+di.<**build-number>.,
or something like: 1.0.0+di.1.abcdef. The build number would be assigned by
the build automation, and would not be checked into git, which is why we
add the sha to the build number. This way, we will never conflict with an
upstream metadata.rb, but can still have a divergent fork. But right now
Chef pukes if you give it a version number that isn’t strictly
...

Greg


#10

Thanks for reviving.

Conversation continues on the ticket, please comment and watch/vote
there. Some Opscode interaction might be useful.

On Fri, Mar 22, 2013 at 4:36 PM, Torben Knerr ukio@gmx.de wrote:

Now that Cookbook Versioning Policy v0.1.0 is out
(https://github.com/chef-community/cvp), it’s a good time to revisit this
discussion.

Do you still need prerelease identifiers or build numbers for cookbooks?

The limitation of the current versioning scheme to be strictly
".." is still one of the pain points for me.

Created CHEF-4027 to bring up the discussion again:
http://tickets.opscode.com/browse/CHEF-4027

Cheers,
Torben

On Wed, Nov 21, 2012 at 7:33 PM, Greg Symons gsymons@drillinginfo.com
wrote:

That’s a good point, and apparently there’s still a lot of discussion
about build numbers going on1. However, even prerelease identifiers, which
were in the 1.0.0 spec, will make Chef unhappy. My main point being, we
can’t start semverring cookbooks in a way that allows the differentiation
between forks and upstream releases without either prerelease identifiers
(which I don’t particularly like overloading for this purpose) or build
numbers (which make more sense to me as site-specific portions of the
version).

Greg

On Wed 21 Nov 2012 11:39:56 AM CST, Jamie Winsor wrote:

While Berkshelf (and Solve) support the latest version of SemVer; it’s
important to note that it is a release candidate and not final.

Build numbers were not in the last finalized release (1.0).

Jamie Winsor
@resetexistence

On Nov 21, 2012, at 12:15 PM, Greg Symons gsymons@drillinginfo.com
wrote:

On Wed 21 Nov 2012 11:07:26 AM CST, Torben Knerr wrote:

+1 for build identifiers

As Greg said, that would finally be a sane ways to differentiate
forked community cookbooks from the upstream ones. As of today,
there’s no sane way of doing this. For sure you could define a
different cookbook location (like “:git => ‘my-fork-of-cookbook-xyz’”)
in a Berksfile or Cheffile, but in the metadata.rb this information is
lost again.

There’s a similar discussion ongoing whether to add a url to the
metadata.rb. I believe this is an attempt to solve the same problem,
but in my opinion, adding the url is too much implemtenation detail.
If we could just add something like version 1.0.1.something that
uniquely identifies a forked version then we wouldn’t need something
like an url in the metadata.rb.

Exactly. For a more concrete example, our convention (if we could:) is
..+di..,
or something like: 1.0.0+di.1.abcdef. The build number would be assigned by
the build automation, and would not be checked into git, which is why we add
the sha to the build number. This way, we will never conflict with an
upstream metadata.rb, but can still have a divergent fork. But right now
Chef pukes if you give it a version number that isn’t strictly
...

Greg