Wiki Navigation

The Puppet Development Life Cycle

This page describes the Puppet Development life cycle. It draws heavily on the OSS Oracle and Linux kernel development processes for the rules and guidelines.

Development Types

There are two types of development in the Puppet community. Core and Non-Core. This document focuses on Core development.

Core

Core development covers development for future release and fixes on the stable branch. All development and fixes will be pushed and merged from developer repositories to the relevant branches in the master repositories (see Repositories below). Little or no development or fixes will take place in the branches of the master repositories. NOTE: It is important to note that currently "master" is the development branch and 0.24.x is stable, so you will almost always want to do your development in 0.24.x. When 0.25.x is released this will swap. The stable branch will be "master" and development will continue in a 0.26.x (or similar) branch. This alignment makes more sense and should make it easier for developers/users to understand where to direct upstream patches.

Non-Core

Non-core development and fixes get developed in developer's private repositories, for example a custom type or function for your site, or a fix specific to you. Some of these may end up in stable or development but if you wish your patches and features to be included then you must follow the Core development process. In some cases commits may potentially be cherry-picked if the branch they are based on hasn't been re-based sufficiently recently.

If you want to increase visibility of your patches and features you should make use of the CommitBot described below to send your commits to the puppet-commit mailing list.

Core Puppet development for developers

This section contains instructions, rules and guidelines for developers who wish to work on Puppet.

Always Work on a Branch

We recommend that you never make changes to the master or stable branch. If you always make changes on a separate branch, you always know that the master branch is representative of the last time you pulled from the Puppet master:

$ git clone git://reductivelabs.com/puppet
$ cd puppet
$ git branch workingbranch master
$ git checkout workingbranch
$ git branch
   master
   * workingbranch
$ vi foo.rb
$ git commit -s -a

Now you can easily see your changes from master or create a set of patches:

$ git diff master workingbranch
$ git format-patch master workingbranch

If changes have been made to the central repository, you can easily grab them. Make sure your working tree is clean (that is, git status is empty of changes), and then:

$ git branch
   master
   * workingbranch
$ git checkout master
$ git pull
... updates master ...
$ git checkout workingbranch

You are back on your working branch, but master is now representative of the Puppet mainline.

Branch Naming Standards

There will largely be two kinds of development: Bug-fixing and new development. Bug fixing should be done in branches named after the ticket, e.g., ticket/1234. New development should be in a feature branch, e.g., feature/awesomeness.

Rebasing

If you are in the process of development over a long period of time it is worth regularly rebasing your branch against the stable or development branch that it was cloned from. You can do this using the git rebase command:

$ git rebase master workingbranch

This will put aside any local changes, update workingbranch with any changes to master and then re-applies any local changes. You may need to resolve any conflicts this creates.

Note that the core developers might ask you to rebase again if it takes much time for them to merge your commit.

Rebasing Workflow

Simle rebasing workflow for master and stable:

$ git branch tickets/0.24.x/xxxx remote/tickets/xxxx
$ git checkout tickets/0.24.x/xxx
$ git rebase 0.24.x
$ git checkout 0.24.x
$ git merge tickets/0.24.x/xxxx
$ git branch -d tickets/0.24.x/xxxx

What is a Patch?

First, what are the rules around what a patch/commit is (I'll use patch from now on). A patch should be:

It must be correct and tested.
It must fix only one thing.
It must clearly articulate what it fixes
It should be committed with the -s option to add the sign-off
It must fix a real bug (one with a ticket)
It can not contain any "trivial" fixes in it (spelling changes, whitespace clean up, etc.) Log these as Redmine tickets and the maintainer will action them.
It should contain no MIME, no links, no compression, no attachments. Just plain text.

Ticket Management

Puppet's development process is keyed off of the ticket database. All patches require a Redmine ticket. All patches should reference the ticket number in their commit message (this might not be possible with all development work but Luke generally tries to add at least a broad tickets to cover all new development activities).

All tickets are Triaged which is the pivot point that determines what happens next with tickets. During the life cycle the ticket may be assigned to one or more members of the development community.

Initially, all tickets are in the Unreviewed stage. From here tickets need to be moved to an appropriate stage. Please see Reports for descriptions of each stage.
At the same time as being moved to the appropriate stage tickets should also be assigned a complexity, priority, and severity. Please see Reports for descriptions of each complexity, priority and severity.
Once tickets reach the Accepted stage they should then be assigned to a particular milestones to indicate in what branch the ticket will be fixed. Please see CodeNames for the current milestones.
After tickets have been placed in the Ready for checkin stage, the patch or fix is applied to the repository and the ticket closed.

If a patch or fix is contained in a single commit then add details of the commit using the hash and branch. If you write the commit hash as commit:"hash" then it will become a click'able Redmine link to the commit after being pulled, for example:

commit:"754129e93de4cc557e600890eab331ec9d0c3107" of branch master

If it is in multiple commits then list each commit in the ticket.

You can also reference issues and automatically close them in commit messages. This is done by using the refs, fixes and closes keywords in commit log messages.

Example of a working commit message using default keywords:

This commit refs #1, #2 and fixes #3

This message would reference issues 1 and 2 and automatically fix issue 3. After a keyword issue IDs can be separated with a space, a comma or &.

Submitting Patches

All patches should be circulated to the -dev list using git-send-email. Here are some brief instructions for doing this:

First, we set-up our environment:

$ git config --global user.name "Your Name"
$ git config --global user.email "yourname@yourdomain.com"
$ git config sendemail.signedoffcc false
$ git config sendemail.suppressfrom true

The first two commands configure your name and email. The next two commands stop Git sending patches to your email address, essentially suppress a CC to you.

Next, we select the commit or commits we want to send and format them as email:
```
$ git format-patch -C -C -M -s -n master..HEAD
```

Your patches should be from the head of the core branch to the head of your branch, which is what the above command does.

When specifying revisions you can use any syntax supported by git-rev-parse (see the "Specifying Revisions" section of the git-rev-parse man page - http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html).

This will output one or more patch files, each prefixed with a patch number, named after the commit log entry and suffixed with .patch. For example, 0001-Removing-extra-debugging.patch.

The git format-patch command line detects changed and renamed files (-C -C -M), adds the "Signed Off by" tag (-s), and keeps count of the patch files being formatted as part of the commit, i.e. [PATCH x/y] (-n).

The patches will be outputted to the current directory or you can override this using the -o option.

Once the patches have been created you can email them to the list using the git send-email command:

$ git send-email --no-chain-reply-to --no-signed-off-by-cc --suppress-from --no-thread --to puppet-dev@googlegroups.com 00*.patch

This will send all patches, not threaded, to the mailing list and cc in any other submitters. Be sure to remove old patches before you provide 00*.patch to git send-email. You don't want to send old patches with the new series!

A Simple Workflow

This a simple workflow for submitting a Puppet patch after review:

Clone the repository and set up a working branch:

$ git clone git://madstop.com/git/puppet.git
$ cd puppet
$ git branch workingbranch master
$ git checkout workingbranch

Make some changes:

$ vi foo.rb
...hack hack hack...
...test test test...
$ git commit -s -a
$ vi bar.rb
...hack hack hack...
...test test test...
$ git commit -s -a

Push the changes to a remote:

$ git branch
  master
  * workingbranch
$ git push remote workingbranch:master

If you don't need the branch anymore delete it:

$ git checkout master
$ git branch -d workingbranch

CommitBot

If you make a commit you should set your Git post-receive hook to make use of a commit bot. The bot should email the details of the commit (including a diff) to the puppet-commit mailing list.

NOTE: Please do not send your commits to the puppet-dev mailing list. Only patches being submitted for comment as part of the patch review process should be sent to this list.

A bot has already been set-up at:

http://git.hjksolutions.com:4011/commit

Or you can download the bot source here and set-up your own.

If you use GitHub you can find information about hooks at GitHub post-receive hooks. If you use your own Git repositories then you can also read about Git post-receive hooks.

BuildBot

Puppet runs a BuildBot to test new code. Each new commit to the current stable and development branches triggers automatic execution of all RSpec and Unit tests.

This process is in development currently and further information including a URL will be available shortly.

URL

Builds Mailing List

IRC Bot - pinocchio

Core Puppet development for maintainers

This is a description of the process for merging and adding patches and commits for maintainers of the various Puppet branches, any this stage stable and development.

Repositories

A full list of developer repositories, including the core repository and third-party developers repositories, is available on the DeveloperRepositories wiki page.

If you intend to submit patches or bug fixes you will need to setup a remote Git repository and add it to the wiki page. It will then be added as a remote repository and your commits can be merged into the stable or development repositories.

Only Work on Branches

Try to avoid making changes on the stable and master branches. If you accidentally type git push without any arguments, the defaults might very well push your current master changes up to the Puppet master. That's probably not what you wanted. Work on a branch, and explicitly tell git push what branch you are pushing from and to.

Current Branches

The current master branch is called master targeted at the elmo or 0.25.x release.
The current stable branch is called 0.24.x and includes the current stable release.
The current deprecated branch is beaker (updated) which is frozen at release 0.23.3.
There are no current feature branches.

You can see a full list of Puppet releases and their code names on the CodeNames wiki page.

Building Releases

To build a release you need to issue some rake commands:

$ rake clean
$ REL=0.24.x rake release

This will bump the version number and build the required packages. This currently needs to be run on the ReductiveLabs master box, laeg.

Also needed will be a manual push of the new Git tag and related commits to the master repository:

$ git push --tags

Download in other formats:

Plain Text