Jump to: navigation, search

Difference between revisions of "Chef/GettingStarted"

(Added in the approved version spec from https://github.com/stackforge/openstack-chef-specs/blob/master/specs/juno/common/cookbook-versioning.rst)
(Update links)
 
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This page serves as a getting started guide for community members interested in contributing to the OpenStack Chef cookbooks and example repository.
+
This page serves as a getting started guide for community members interested in introducing themselves to the OpenStack Chef cookbooks and community.
  
 
==Communication==
 
==Communication==
  
* The OpenStack + Chef community has a mailing list on Google Groups. Join the conversation: https://groups.google.com/forum/?fromgroups=#!forum/opscode-chef-openstack
+
* The OpenStack + Chef community leverages the main [http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss openstack-discuss mailing list] with the tag of [chef] in the subject line.
*There is an '''#openstack-chef''' channel on Freenode.net. Come hang out with us and collaborate there.
+
* There is an [https://webchat.freenode.net/?channels=openstack-chef #openstack-chef channel] on freenode.net. Come hang out with us and collaborate there.
 +
* We have a maintainers list located [https://opendev.org/openstack/openstack-chef-specs/src/branch/master/MAINTAINERS.md here]. Please don't hesitate to reach out.
  
 
==Bug Tracking==
 
==Bug Tracking==
Line 13: Line 14:
  
 
For major feature enhancements and planning you can use Launchpad's Blueprints system for the OpenStack + Chef project on Launchpad. You can [https://blueprints.launchpad.net/openstack-chef/+addspec create a new blueprint] that may be targeted to a milestone and tracked appropriately.
 
For major feature enhancements and planning you can use Launchpad's Blueprints system for the OpenStack + Chef project on Launchpad. You can [https://blueprints.launchpad.net/openstack-chef/+addspec create a new blueprint] that may be targeted to a milestone and tracked appropriately.
The process for blueprint content reviews is documented here: https://github.com/stackforge/openstack-chef-specs
+
The process for blueprint content reviews is documented here: https://opendev.org/openstack/openstack-chef-specs
  
==Code==
+
==How to Contribute==
 
+
We have broken this off into another page [https://wiki.openstack.org/wiki/Chef/Contributing here].
The canonical upstream Chef cookbooks and example repository are located in the [https://github.com/stackforge Stackforge Github organization]. There is a single Chef cookbook for each integrated OpenStack project:
 
 
 
* [https://github.com/stackforge/cookbook-openstack-block-storage OpenStack Block Storage (Cinder) cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-compute OpenStack Compute (Nova) cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-dashboard OpenStack Dashboard (Horizon) cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-data-processing OpenStack Data Processing (Sahara) cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-database OpenStack Database (Trove) cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-identity OpenStack Identity (Keystone) cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-image OpenStack Image (Glance) cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-network OpenStack Network (formerly known as Quantum) cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-object-storage OpenStack Object Storage (Swift) cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-orchestration OpenStack Orchestration (Heat) cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-telemetry OpenStack Telemetry (formerly known as Metering) (Ceilometer) cookbook]
 
 
 
In addition to the project cookbooks, there are five support cookbooks:
 
 
 
* [https://github.com/stackforge/cookbook-openstack-common Common library cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-ops-database Example database configuration cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-ops-messaging Example message queue configuration cookbook]
 
* [https://github.com/stackforge/cookbook-openstack-integration-test OpenStack Integration Test Suite (Tempest) cookbook]
 
* [https://github.com/stackforge/cookbook-ceph Ceph, a distributed network storage and filesystem cookbook]
 
 
 
As well as an example [http://docs.opscode.com/essentials_repository.html Chef Repository] that sets up an OpenStack environment:
 
 
 
* [https://github.com/stackforge/openstack-chef-repo Example OpenStack Chef Repository]
 
 
 
===Contributing to the OpenStack Chef Cookbooks===
 
 
 
See [http://www.joinfu.com/2013/05/working-with-the-openstack-code-review-and-ci-system-chef-edition/ this blog entry] for an introduction to contributing and pushing code to for the OpenStack Chef cookbooks housed on Stackforge.
 
 
 
===Guidelines for Commit Messages===
 
 
 
Please try to make commit messages useful. Read [http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html this excellent blog post], as well as the [[GitCommitMessages|standard commit message guidelines for OpenStack projects]] before making your first code push.
 
 
 
===Guidelines for Code Reviewers===
 
 
 
Here are some simple rules for reviewers of code on the [https://review.openstack.org Gerrit Review site]:
 
 
 
'''Rule #1''': Never +1/+2R or +1A your own patch.
 
 
 
'''Rule #2''': All patches must have a commit message that meets the [[GitCommitMessages|standard commit message guidelines for OpenStack projects]]. Failure of the commit message to meet these guidelines should prevent a +1A by a core reviewer.
 
 
 
'''Rule #3''': If the patch is more than just stylistic or typo fixes, it requires at least 2 core reviewers to add a +2R to the review before any core reviewer can +1A the review.
 
 
 
'''Rule #4''': If the patch '''''changes''''' existing behavior of any cookbook in a backwards-incompatible way, a corresponding bump in the version in the cookbook's metadata.rb must be included in patch set. Failure to do so should prevent a +1A by a core reviewer.
 
 
 
'''Rule #5''': If the patch '''''adds''''' additional functionality to a '''''library''''' cookbook, a corresponding bump in version number in the metadata.rb file should accompany the patch. Failure to do so should prevent a +1A by a core review.
 
 
 
===Guidelines for Version Changes===
 
 
 
When submitting cookbook patches, it is generally required that the version
 
number (within metadata.rb) is incremented in a manor reflective of the level
 
of the change.  Any patch should also update the CHANGELOG.md and if appropriate
 
the README.md should reflect the changes and any relevant how-to instructions. The
 
CHANGELOG.md is our executive summary of changes, it should inform what the change
 
was in a quick manner.
 
 
 
There are some differences between the development of patches on the Master and
 
Stable branches.  There is more restrictive and vigorous oversight given to changes
 
on the Stable branches.  The Master branch is bleeding edge and can relax the
 
version requirement in some simple cases to allow for increased productivity.
 
 
 
====Semantic Versioning====
 
 
 
The cookbooks use the Semantic Versioning system (see http://semver.org)
 
The system uses a three part version number, Major.Minor.Patch.
 
For example: 9.2.33
 
 
 
The Major number shouldn't change within a development branch. It will reflect the
 
number that is the Alphabetized Letter of the base Openstack release,
 
see: https://wiki.openstack.org/wiki/Releases.  An example would be Icehouse
 
being the 9th letter and the 9th release all the stable cookbooks would be 9.Y.Z.
 
When the Master branch becomes stabilized, a new Stable branch will be created from
 
it and the Major number in the Master will be incremented by the core team.
 
 
 
The Minor and Patch numbers will be incremented as described in the branch specific
 
sections below.
 
 
 
====Stable Branch====
 
 
 
The Stable branch cookbooks must leverage the Semantic Versioning system exclusively.
 
All patches must update the metadata.rb and the CHANGELOG.md at a minimum.
 
All patches should try to be backwards compatible.
 
 
 
{| class="wikitable"
 
|-
 
! Stable Branch Example Situations !! Level of Change
 
|-
 
| add a recipe || Increment Minor
 
|-
 
| add a function or method || Increment Minor
 
|-
 
| change Gemfile or Berksfile || Increment Minor
 
|-
 
| backport a fix from Master branch || Increment Minor
 
|-
 
| add attribute for a value in a configuration file with the same default || Increment Patch
 
|-
 
| changing a resource option || Increment Patch
 
|-
 
| add a test || Increment Patch
 
|-
 
| fix a broken recipe || Increment Patch
 
|-
 
| re-factoring recipe or test || Increment Patch
 
|}
 
 
 
The table above shows some examples of different levels of changes introduced by a patch and
 
what part of the version number to increment for Stable branches.
 
 
 
=====Version Locking=====
 
 
 
The Stable branches are also locked down by added Berksfile.lock and Gemfile.lock to each
 
cookbook.  If any changes are made to the Gemfile, the Gemfile.lock would also have to be
 
updated.  If any changes are dependent upon other cookbook changes, then the Berkfile.lock
 
and metadata.rb files would need to be updated accordingly.
 
 
 
=====Cookbook Dependencies=====
 
 
 
When a change requires hits to multiple cookbooks, like when adding attributes to Common, the
 
metadata.rb file would need to be updated to reflect that required version level.  The
 
Berksfile.lock would also need to be updated with the commit id of the dependent change.
 
 
 
====Master Branch====
 
 
 
The master cookbook should leverage the Semantic Versioning system lightly.
 
We consider the master branch a fast paced "Work in Progress" until we come to the Release
 
Candidate 1 date (RC-1). This means it will be under rapid and active development where
 
versioning isn't always required.
 
All patches must update the the CHANGELOG.md at a minimum.
 
 
 
 
 
{| class="wikitable"
 
|-
 
! Master Branch Example Situations !! Level of Change
 
|-
 
| Branching for a new Stable branch || Increment Major
 
|-
 
| add a recipe || Increment Minor
 
|-
 
| add a function or method || Increment Minor
 
|-
 
| change Gemfile or Berksfile || Increment Minor
 
|-
 
| add attribute for a value in a configuration file with the same default || Increment Patch**
 
|-
 
| changing a resource option || Increment Patch**
 
|-
 
| add a test || Increment Patch**
 
|-
 
| fix a broken recipe || Increment Patch**
 
|-
 
| re-factoring recipe or test || Increment Patch**
 
|}
 
 
 
The table above shows some examples of different levels of changes introduced by a patch and
 
what part of the version number to increment for Master branches.
 
 
 
(**) There are cases where incrementing the Patch number is not necessary and only updating the
 
CHANGELOG.md is required.  To avoid re-base collisions on Patch number changes and allow more
 
rapid development, if the change falls within these guidelines, incrementing the Patch version
 
would not be required.
 
* When the change only effects a single cookbook
 
* When the change is just a simple addition of a new attribute for a template and no other logic change is required
 
* When a patch only effects the tests
 
* When a patch only effect the README or other comments
 
 
 
=====Version Locking=====
 
 
 
The Master branch is NOT locked down a Berksfile.lock or Gemfile.lock.  Changes to the Berksfile
 
and Gemfile can be made directly.
 
 
 
=====Cookbook Dependencies=====
 
 
 
When a change requires hits to multiple cookbooks, like when adding attributes to Common, the
 
metadata.rb file would need to be updated to reflect that required version level.
 

Latest revision as of 11:12, 2 September 2019

This page serves as a getting started guide for community members interested in introducing themselves to the OpenStack Chef cookbooks and community.

Communication

  • The OpenStack + Chef community leverages the main openstack-discuss mailing list with the tag of [chef] in the subject line.
  • There is an #openstack-chef channel on freenode.net. Come hang out with us and collaborate there.
  • We have a maintainers list located here. Please don't hesitate to reach out.

Bug Tracking

We track bugs and feature requests using a single Launchpad project called OpenStack + Chef. You can see the list of open bugs or file a new bug.

Blueprints / Feature Tracking

For major feature enhancements and planning you can use Launchpad's Blueprints system for the OpenStack + Chef project on Launchpad. You can create a new blueprint that may be targeted to a milestone and tracked appropriately. The process for blueprint content reviews is documented here: https://opendev.org/openstack/openstack-chef-specs

How to Contribute

We have broken this off into another page here.