From 9bfa068251af5bb555eb9f2becd2a12a1019797f Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 23 Sep 2013 18:26:12 -0400 Subject: [PATCH] Cleanup Gemfile and markdown formatting --- .kitchen.yml | 78 +++++---------- Berksfile | 4 +- CONTRIBUTING | 29 ------ CONTRIBUTING.md | 257 ++++++++++++++++++++++++++++++++++++++++++++++++ Gemfile | 14 ++- README.md | 31 ++++++ TESTING.md | 58 ++++++++--- 7 files changed, 368 insertions(+), 103 deletions(-) delete mode 100644 CONTRIBUTING create mode 100644 CONTRIBUTING.md diff --git a/.kitchen.yml b/.kitchen.yml index d63d45dca..7cd08656a 100644 --- a/.kitchen.yml +++ b/.kitchen.yml @@ -1,4 +1,3 @@ ---- driver_plugin: vagrant driver_config: require_chef_omnibus: true @@ -6,56 +5,31 @@ driver_config: memory: 1024 platforms: -- name: ubuntu-12.04 - driver_config: - box: opscode-ubuntu-12.04 - box_url: https://opscode-vm-bento.s3.amazonaws.com/vagrant/opscode_ubuntu-12.04_provisionerless.box - run_list: - - recipe[apt] - -- name: ubuntu-10.04 - driver_config: - box: opscode-ubuntu-10.04 - box_url: https://opscode-vm-bento.s3.amazonaws.com/vagrant/opscode_ubuntu-10.04_provisionerless.box - run_list: - - recipe[apt] - -- name: centos-6.4 - driver_config: - box: opscode-centos-6.4 - box_url: https://opscode-vm-bento.s3.amazonaws.com/vagrant/opscode_centos-6.4_provisionerless.box - run_list: - - recipe[yum::epel] -- name: centos-5.9 - driver_config: - box: opscode-centos-5.9 - box_url: https://opscode-vm-bento.s3.amazonaws.com/vagrant/opscode_centos-5.9_provisionerless.box - run_list: - - recipe[yum::epel] + - name: ubuntu-12.04 + run_list: + - recipe[apt] + - name: ubuntu-10.04 + run_list: + - recipe[apt] + - name: centos-6.4 + - name: centos-5.9 suites: -- name: default - run_list: - - recipe[php] - attributes: {} - -- name: source - run_list: - - recipe[php] - attributes: - php: - install_method: source - -- name: module-packages - run_list: - - recipe[php] - - recipe[php::module_apc] - - recipe[php::module_curl] - - recipe[php::module_fpdf] - - recipe[php::module_gd] - - recipe[php::module_ldap] - - recipe[php::module_memcache] - - recipe[php::module_mysql] - - recipe[php::module_pgsql] - - recipe[php::module_sqlite3] - attributes: {} + - name: default + run_list: + - recipe[php::default] + - name: source + run_list: + - recipe[php::source] + - name: module-packages + run_list: + - recipe[php::default] + - recipe[php::module_apc] + - recipe[php::module_curl] + - recipe[php::module_fpdf] + - recipe[php::module_gd] + - recipe[php::module_ldap] + - recipe[php::module_memcache] + - recipe[php::module_mysql] + - recipe[php::module_pgsql] + - recipe[php::module_sqlite3] diff --git a/Berksfile b/Berksfile index 34a3b2d83..3b5ff95f2 100644 --- a/Berksfile +++ b/Berksfile @@ -1,8 +1,6 @@ site :opscode - metadata group :integration do - cookbook "apt" - cookbook "yum" + cookbook 'apt', '~> 2.0' end diff --git a/CONTRIBUTING b/CONTRIBUTING deleted file mode 100644 index 89ac873b4..000000000 --- a/CONTRIBUTING +++ /dev/null @@ -1,29 +0,0 @@ -If you would like to contribute, please open a ticket in JIRA: - -* http://tickets.opscode.com - -Create the ticket in the COOK project and use the cookbook name as the -component. - -For all code contributions, we ask that contributors sign a -contributor license agreement (CLA). Instructions may be found here: - -* http://wiki.opscode.com/display/chef/How+to+Contribute - -When contributing changes to individual cookbooks, please do not -modify the version number in the metadata.rb. Also please do not -update the CHANGELOG.md for a new version. Not all changes to a -cookbook may be merged and released in the same versions. Opscode will -handle the version updates during the release process. You are welcome -to correct typos or otherwise make updates to documentation in the -README. - -If a contribution adds new platforms or platform versions, indicate -such in the body of the commit message(s), and update the relevant -COOK ticket. When writing commit messages, it is helpful for others if -you indicate the COOK ticket. For example: - - git commit -m '[COOK-1041] Updated pool resource to correctly delete.' - -In the ticket itself, it is also helpful if you include log output of -a successful Chef run, but this is not absolutely required. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..3a9989787 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,257 @@ +# Contributing to Opscode Cookbooks + +We are glad you want to contribute to Opscode Cookbooks! The first +step is the desire to improve the project. + +You can find the answers to additional frequently asked questions +[on the wiki](http://wiki.opscode.com/display/chef/How+to+Contribute). + +You can find additional information about +[contributing to cookbooks](http://wiki.opscode.com/display/chef/How+to+Contribute+to+Opscode+Cookbooks) +on the wiki as well. + +## Quick-contribute + +* Create an account on our [bug tracker](http://tickets.opscode.com) +* Sign our contributor agreement (CLA) +[ online](https://secure.echosign.com/public/hostedForm?formid=PJIF5694K6L) +(keep reading if you're contributing on behalf of your employer) +* Create a ticket for your change on the + [bug tracker](http://tickets.opscode.com) +* Link to your patch as a rebased git branch or pull request from the + ticket +* Resolve the ticket as fixed + +We regularly review contributions and will get back to you if we have +any suggestions or concerns. + +## The Apache License and the CLA/CCLA + +Licensing is very important to open source projects, it helps ensure +the software continues to be available under the terms that the author +desired. Chef uses the Apache 2.0 license to strike a balance between +open contribution and allowing you to use the software however you +would like to. + +The license tells you what rights you have that are provided by the +copyright holder. It is important that the contributor fully +understands what rights they are licensing and agrees to them. +Sometimes the copyright holder isn't the contributor, most often when +the contributor is doing work for a company. + +To make a good faith effort to ensure these criteria are met, Opscode +requires a Contributor License Agreement (CLA) or a Corporate +Contributor License Agreement (CCLA) for all contributions. This is +without exception due to some matters not being related to copyright +and to avoid having to continually check with our lawyers about small +patches. + +It only takes a few minutes to complete a CLA, and you retain the +copyright to your contribution. + +You can complete our contributor agreement (CLA) +[ online](https://secure.echosign.com/public/hostedForm?formid=PJIF5694K6L). +If you're contributing on behalf of your employer, have your employer +fill out our +[Corporate CLA](https://secure.echosign.com/public/hostedForm?formid=PIE6C7AX856) +instead. + +## Ticket Tracker (JIRA) + +The [ticket tracker](http://tickets.opscode.com) is the most important +documentation for the code base. It provides significant historical +information, such as: + +* Which release a bug fix is included in +* Discussion regarding the design and merits of features +* Error output to aid in finding similar bugs + +Each ticket should aim to fix one bug or add one feature. + +## Using git + +You can get a quick copy of the repository for this cookbook by +running `git clone +git://github.com/opscode-coobkooks/COOKBOOKNAME.git`. + +For collaboration purposes, it is best if you create a Github account +and fork the repository to your own account. Once you do this you will +be able to push your changes to your Github repository for others to +see and use. + +If you have another repository in your GitHub account named the same +as the cookbook, we suggest you suffix the repository with -cookbook. + +### Branches and Commits + +You should submit your patch as a git branch named after the ticket, +such as COOK-1337. This is called a _topic branch_ and allows users to +associate a branch of code with the ticket. + +It is a best practice to have your commit message have a _summary +line_ that includes the ticket number, followed by an empty line and +then a brief description of the commit. This also helps other +contributors understand the purpose of changes to the code. + + [COOK-1757] - platform_family and style + + * use platform_family for platform checking + * update notifies syntax to "resource_type[resource_name]" instead of + resources() lookup + * COOK-692 - delete config files dropped off by packages in conf.d + * dropped debian 4 support because all other platforms have the same + values, and it is older than "old stable" debian release + +Remember that not all users use Chef in the same way or on the same +operating systems as you, so it is helpful to be clear about your use +case and change so they can understand it even when it doesn't apply +to them. + +### Github and Pull Requests + +All of Opscode's open source cookbook projects are available on +[Github](http://www.github.com/opscode-cookbooks). + +We don't require you to use Github, and we will even take patch diffs +attached to tickets on the tracker. However Github has a lot of +convenient features, such as being able to see a diff of changes +between a pull request and the main repository quickly without +downloading the branch. + +If you do choose to use a pull request, please provide a link to the +pull request from the ticket __and__ a link to the ticket from the +pull request. Because pull requests only have two states, open and +closed, we can't easily filter pull requests that are waiting for a +reply from the author for various reasons. + +### More information + +Additional help with git is available on the +[Working with Git](http://wiki.opscode.com/display/chef/Working+with+Git) +wiki page. + +## Functional and Unit Tests + +This cookbook is set up to run tests under +[Opscode's test-kitchen](https://github.com/opscode/test-kitchen). It +uses minitest-chef to run integration tests after the node has been +converged to verify that the state of the node. + +Test kitchen should run completely without exception using the default +[baseboxes provided by Opscode](https://github.com/opscode/bento). +Because Test Kitchen creates VirtualBox machines and runs through +every configuration in the Kitchenfile, it may take some time for +these tests to complete. + +If your changes are only for a specific recipe, run only its +configuration with Test Kitchen. If you are adding a new recipe, or +other functionality such as a LWRP or definition, please add +appropriate tests and ensure they run with Test Kitchen. + +If any don't pass, investigate them before submitting your patch. + +Any new feature should have unit tests included with the patch with +good code coverage to help protect it from future changes. Similarly, +patches that fix a bug or regression should have a _regression test_. +Simply put, this is a test that would fail without your patch but +passes with it. The goal is to ensure this bug doesn't regress in the +future. Consider a regular expression that doesn't match a certain +pattern that it should, so you provide a patch and a test to ensure +that the part of the code that uses this regular expression works as +expected. Later another contributor may modify this regular expression +in a way that breaks your use cases. The test you wrote will fail, +signalling to them to research your ticket and use case and accounting +for it. + +If you need help writing tests, please ask on the Chef Developer's +mailing list, or the #chef-hacking IRC channel. + +## Code Review + +Opscode regularly reviews code contributions and provides suggestions +for improvement in the code itself or the implementation. + +We find contributions by searching the ticket tracker for _resolved_ +tickets with a status of _fixed_. If we have feedback we will reopen +the ticket and you should resolve it again when you've made the +changes or have a response to our feedback. When we believe the patch +is ready to be merged, we will tag the _Code Reviewed_ field with +_Reviewed_. + +Depending on the project, these tickets are then merged within a week +or two, depending on the current release cycle. + +## Release Cycle + +The versioning for Opscode Cookbook projects is X.Y.Z. + +* X is a major release, which may not be fully compatible with prior + major releases +* Y is a minor release, which adds both new features and bug fixes +* Z is a patch release, which adds just bug fixes + +A released version of a cookbook will end in an even number, e.g. +"1.2.4" or "0.8.0". When development for the next version of the +cookbook begins, the "Z" patch number is incremented to the next odd +number, however the next release of the cookbook may be a major or +minor incrementing version. + +Releases of Opscode's cookbooks are usually announced on the Chef user +mailing list. Releases of several cookbooks may be batched together +and announced on the [Opscode Blog](http://www.opscode.com/blog). + +## Working with the community + +These resources will help you learn more about Chef and connect to +other members of the Chef community: + +* [chef](http://lists.opscode.com/sympa/info/chef) and + [chef-dev](http://lists.opscode.com/sympa/info/chef-dev) mailing + lists +* #chef and #chef-hacking IRC channels on irc.freenode.net +* [Community Cookbook site](http://community.opscode.com) +* [Chef wiki](http://wiki.opscode.com/display/chef) +* Opscode Chef [product page](http://www.opscode.com/chef) + + +## Cookbook Contribution Do's and Don't's + +Please do include tests for your contribution. If you need help, ask +on the +[chef-dev mailing list](http://lists.opscode.com/sympa/info/chef-dev) +or the +[#chef-hacking IRC channel](http://community.opscode.com/chat/chef-hacking). +Not all platforms that a cookbook supports may be supported by Test +Kitchen. Please provide evidence of testing your contribution if it +isn't trivial so we don't have to duplicate effort in testing. Chef +10.14+ "doc" formatted output is sufficient. + +Please do indicate new platform (families) or platform versions in the +commit message, and update the relevant ticket. + +If a contribution adds new platforms or platform versions, indicate +such in the body of the commit message(s), and update the relevant +COOK ticket. When writing commit messages, it is helpful for others if +you indicate the COOK ticket. For example: + + git commit -m '[COOK-1041] - Updated pool resource to correctly + delete.' + +Please do use [foodcritic](http://acrmp.github.com/foodcritic) to +lint-check the cookbook. Except FC007, it should pass all correctness +rules. FC007 is okay as long as the dependent cookbooks are *required* +for the default behavior of the cookbook, such as to support an +uncommon platform, secondary recipe, etc. + +Please do ensure that your changes do not break or modify behavior for +other platforms supported by the cookbook. For example if your changes +are for Debian, make sure that they do not break on CentOS. + +Please do not modify the version number in the metadata.rb, Opscode +will select the appropriate version based on the release cycle +information above. + +Please do not update the CHANGELOG.md for a new version. Not all +changes to a cookbook may be merged and released in the same versions. +Opscode will update the CHANGELOG.md when releasing a new version of +the cookbook. diff --git a/Gemfile b/Gemfile index 833e0fc3f..f554350d4 100644 --- a/Gemfile +++ b/Gemfile @@ -1,5 +1,11 @@ -source :rubygems +source 'https://rubygems.org' -gem 'test-kitchen', '< 1.0' -gem 'kitchen-vagrant', :group => :integration -gem 'berkshelf' +gem 'berkshelf', '~> 2.0' +gem 'chefspec', '~> 2.0' +gem 'foodcritic', '~> 2.2' +gem 'rubocop', '~> 0.12' + +group :integration do + gem 'test-kitchen', '~> 1.0.0.beta' + gem 'kitchen-vagrant', '~> 0.11' +end diff --git a/README.md b/README.md index 4153861dd..5cc2cf6a3 100644 --- a/README.md +++ b/README.md @@ -211,6 +211,37 @@ run_list( ``` +Development +----------- +This section details "quick development" steps. For a detailed explanation, see [[Contributing.md]]. + +1. Clone this repository from GitHub: + + $ git clone git@github.com:opscode-cookbooks/php.git + +2. Create a git branch + + $ git checkout -b my_bug_fix + +3. Install dependencies: + + $ bundle install + +4. Make your changes/patches/fixes, committing appropiately +5. **Write tests** +6. Run the tests: + - `bundle exec foodcritic -f any .` + - `bundle exec rspec` + - `bundle exec rubocop` + - `bundle exec kitchen test` + + In detail: + - Foodcritic will catch any Chef-specific style errors + - RSpec will run the unit tests + - Rubocop will check for Ruby-specific style errors + - Test Kitchen will run and converge the recipes + + License & Authors ----------------- - Author:: Seth Chisamore () diff --git a/TESTING.md b/TESTING.md index e29ff7c04..b4102e321 100644 --- a/TESTING.md +++ b/TESTING.md @@ -1,25 +1,53 @@ -This cookbook includes support for running tests via Test Kitchen (1.0). This has some requirements. +This cookbook uses a variety of testing components: -1. You must be using the Git repository, rather than the downloaded cookbook from the Chef Community Site. -2. You must have Vagrant 1.1 installed. -3. You must have a "sane" Ruby 1.9.3 environment. +- Unit tests: [ChefSpec](https://github.com/acrmp/chefspec) +- Integration tests: [Test Kitchen](https://github.com/opscode/test-kitchen) +- Chef Style lints: [Foodcritic](https://github.com/acrmp/foodcritic) +- Ruby Style lints: [Rubocop](https://github.com/bbatsov/rubocop) -Once the above requirements are met, install the additional requirements: -Install the berkshelf plugin for vagrant, and berkshelf to your local Ruby environment. +Prerequisites +------------- +To develop on this cookbook, you must have a sane Ruby 1.9+ environment. Given the nature of this installation process (and it's variance across multiple operating systems), we will leave this installation process to the user. - vagrant plugin install vagrant-berkshelf - gem install berkshelf +You must also have `bundler` installed: -Install Test Kitchen 1.0 (unreleased yet, use the alpha / prerelease version). + $ gem install bundler - gem install test-kitchen --pre +You must also have Vagrant and VirtualBox installed: -Install the Vagrant driver for Test Kitchen. +- [Vagrant](https://vagrantup.com) +- [VirtualBox](https://virtualbox.org) - gem install kitchen-vagrant +Once installed, you must install the `vagrant-berkshelf` plugin: -Once the above are installed, you should be able to run Test Kitchen: + $ vagrant plugin install vagrant-berkshelf - kitchen list - kitchen test + +Development +----------- +1. Clone the git repository from GitHub: + + $ git clone git@github.com:opscode-cookbooks/COOKBOOK.git + +2. Install the dependencies using bundler: + + $ bundle install + +3. Create a branch for your changes: + + $ git checkout -b my_bug_fix + +4. Make any changes +5. Write tests to support those changes. It is highly recommended you write both unit and integration tests. +6. Run the tests: + - `bundle exec rspec` + - `bundle exec foodcritic .` + - `bundle exec rubocop` + - `bundle exec kitchen test` + +7. Assuming the tests pass, open a Pull Request on GitHub +8. Open a JIRA ticket for this compontent, linking the JIRA ticket to the Pull Request and visa versa. +9. Mark the JIRA ticket as "Fix Provided" + +For more information, see [Opscode's Contribution Guidelines](https://wiki.opscode.com/display/chef/How+to+Contribute).