miketheman/knife-community

A Knife plugin to assist with deploying completed Chef cookbooks to the Chef Supermarket

knife-community

A Knife plugin to assist with deploying completed Chef cookbooks to the Chef Supermarket.

Intro

There are sooo many ways to deliver software. Apt has 'deb', Yum has 'rpm', Node has 'npm', RubyGems has 'gem', Java has 'jar', etc etc etc.

In The Land of Chef, the typical unit of shareable software is a 'cookbook'.

The centralized location for sharing cookbooks is the Supermarket, and we already have support to download/install these elements, either it be through knife itself, librarian, and berkshelf, and there are probably others.

What we don't have is a good method for cookbook maintainers to contribute back to the Supermarket, while semi-enforcing good habits, such as version incrementing, git tags and forming the package correctly.

Assumptions

Basics

• You know what Git is
• You know what Chef is
• You have Push permissions to the remote GitHub repository
• You don't already have a perfected workflow that works for you
• You want to be a helpful citizen of the community

Important

• You have not incremented the version number in metadata.rb - this will do so for you
• You have a name string defined in your metadata.rb, OR your repository name is identical to your cookbook name
• You have either committed or staged all changes to be included with this version release. Any uncommitted changed should be git stashed, or stage them to be committed along with the version via git add

Cookbook Release Workflow

Assuming you have made your changes, tested your code thoroughly (one can hope!), all merged into your master branch, and are ready to release a new version of your cookbook, here's a flow to follow:

1. Ensure that the branch is ready to be committed. If there are uncommitted changes, error out.
2. Read in the current metadata.rb, inspect the version string, and increment it to the next tiny version. Override with CLI argument.
3. Create a git commit for the metadata.rb change.
4. Create a git tag with the version number (no leading "v" or the like)
5. Push all commits/tags to the set remote, typically like git push origin master. Override with --branch
6. Create a 'package' - effectively a compressed tarball - and upload it to the Supermarket
7. Have a beer, or glass of wine - you choose.

This flow can probably be used for most cookbook maintainers.

Usage

Invoke

knife community release COOKBOOK [X.Y.Z | --remote | --branch | --devodd ]

Flags

• X.Y.Z - String, Version in X.Y.Z format. Manually specify the version.

  If unspecified, increments to the next x.y.Z version

• --remote REMOTE - String, Remote repository to push to. Defaults to origin

• --branch BRANCHNAME - String, Branch name. Defaults to master

• --devodd - Boolean. If specified, post-release, will bump the minor version to the next odd number, and generate another commit & push (but no tags).

  This is a flow that some adopt by having even-only numbered releases, utilizing the odd numbered ones for development.

There are other flags, run knife community release -h to see their specifications.

Some good ideas while working on a cookbook

Creating a CHANGELOG.md that details a short message about any changes included in each release is really helpful to anyone looking at your updated cookbook and seeing if it addresses a problem they have, without delving deeper into the code.

See the CHANGELOG for this project to get an idea of how to write one.

Updating a TODO.md file if there are outstanding known issues, planned work for the next version, etc. A TODO file also helps anyone else in the community try to tackle a problem you haven't figured out or gotten to yet, so they can issue a pull request for your cookbook.

Follow Semantic Versioning when choosing which version number to increment to. Start your cookbook at 0.1.0, and increment from there, until you are confident enough in a 1.0.0 version.

Test, test, test. And then test again.

knife-community's Issues

Agreeable to adding option for "vX.Y.Z" style tagging?

I can help with the work on this, but would much prefer if tagged releases of my cookbooks were of the form "v1.0.4" (vs. "1.0.4"). This allows you to sort and differentiate all release tags from other arbitrary ones. It's also the default style that Bundler and Jeweler use when releasing gems.

An opt-in flag is fine by me; it's about the only blocker for me to use this for all cookbook releases.

Thanks!

Partial duplication of efforts?

Firstly, love the idea of making community site contributions simpler -- i kept meaning to get around to figuring it out, and this is going to make it simple :)

Any thoughts on the similarities with this plugin?
https://github.com/Atalanta/knife-cookbook-bump

//cc @Atalanta @fnichol

Use Chef::Knife::CookbookSiteShare instead of shellout to command

The share_new_version method uses shellout to the knife cookbook site share command, rather than using the Chef::Knife::CookbookSiteShare class.

      # The use the existing knife command to tarball & share.
      # This could possibly done in a more elegant fashion than shelling out again.
      knife_ckbk_path = "-o #{config[:cookbook_path].join(':')}" if !config[:cookbook_path].nil?
      shellout("knife cookbook site share #{@cb_name} #{category} #{knife_ckbk_path}")

the `gsub!` that changes version number in metadata.rb is not specific enough

TL;DR - ALL THE VERSIONS are bumped, not just the cookbook's version.

An example of the commit that was produced:

% git show HEAD
commit ef24858cd4665dd68af28a4fde93995c7a1e552e
Author: Seth Chisamore <[email protected]>
Date:   Wed Feb 27 09:45:18 2013 -0500

    release v1.0.5

diff --git a/metadata.rb b/metadata.rb
index 1769b92..0be9655 100644
--- a/metadata.rb
+++ b/metadata.rb
@@ -4,7 +4,7 @@ maintainer_email "[email protected]"
 license          "All rights reserved"
 description      "Installs/Configures Opscode CI clusters"
 long_description IO.read(File.join(File.dirname(__FILE__), 'README.md'))
-version          "1.0.4"
+version          "1.0.5"

 # internal cookbooks
 depends "opscode-github"
@@ -20,6 +20,6 @@ depends "ntp", "~> 1.3.2"
 depends "python", "~> 1.2.2"
 depends "rbenv", "~> 1.4.1"
 depends "rsyslog", "~> 1.5.0"
-depends "runit", "~> 1.0.4"
+depends "runit", "~> 1.0.5"
 depends "sudo", "~> 2.0.4"
 depends "users", "~> 1.3.0"

Update for Chef 11

With Chef 11 installed:

/Users/jtimberman/.rbenv/versions/1.9.3-p327/lib/ruby/1.9.1/rubygems/specification.rb:1637:in `raise_if_conflicts': Unable to activate knife-community-0.0.1, because chef-11.0.0 conflicts with chef (~> 10) (Gem::LoadError)

Github description still mentions community site

That should probably get updated for Supermarket

Include default ignore file

There should be a list of files that are ignored by default:

# Put files/directories that should be ignored in this file when uploading
# or sharing to the community site

# Compiled source #
###################
*.com
*.class
*.dll
*.exe
*.o
*.so
*/rdoc/

# Packages #
############
# it's better to unpack these files and commit the raw source
# git has its own built in compression methods
*.7z
*.dmg
*.gz
*.iso
*.jar
*.rar
*.tar
*.zip

# Logs and databases #
######################
*.log
*.sql
*.sqlite

# OS generated files #
######################
.DS_Store
ehthumbs.db
Icon?
Thumbs.db

# SASS #
########
.sass-cache

# Bundler #
###########
.bundle

# POW #
#######
.pow
.powrc
.powenv

# Other Stuff #
###############
.project
.settings

# Editor #
##########
*~
*.sw[a-z]

# Subversion #
##############
.svn
*/.svn

# Git #
#######
.git
*/.git
.gitignore
.gitmodules
.gitconfig
.gitattributes

# Spec #
########
.rspec

# Ruby #
########
.rvmrc
.rbenv-version
Gemfile
Gemfile.lock
Rakefile

# Travis #
##########
.travis.yml

# Cookbook #
############
CONTRIBUTING*
CHANGELOG*
Colanderfile
Berksfile
Berksfile.lock
.colander
tmp

Is this plugin still worthwhile?

Due to the inventions of emeril, stove, knife-supermarket, is this plugin still a valuable resource?

I've been spending some time recently to see if refactoring this into better methods and testable functionality (as well as replace some of the git functions with better ones), but I don't know if it's with the effort.

conflict mixlib-shellout

After a fresh:

gem install chef
gem install berkshelf
gem install knife-community

I have an error:

knife community release --help
/home/guilhem/.rvm/rubies/ruby-1.9.3-p448/lib/ruby/site_ruby/1.9.1/rubygems/specification.rb:1638:in `raise_if_conflicts': Unable to activate knife-community-0.2.0, because mixlib-shellout-1.2.0 conflicts with mixlib-shellout (~> 1.1.0) (Gem::LoadError)

I bypass this by:
gem uninstall mixlib-shellout -v 1.2.0

Update travis testing for Chef 11

Look at using ruby-git instead of Grit

https://github.com/schacon/ruby-git

Honor chefignore

As I see, knife community doesn't honor chefignore file.

Push to private git repo

Is there an override option that lets me specify a private git repo url to push this to?