Patch Contents

Work in progress collection of content requirements:

• patches to core stuff should always contain tests (see luke's comment on #884)
• four spaces indentation (see luke's comment on #896)

Use Git

These instructions seem to assume a certain minimum version of git, as 1.1.3 doesn't appear to have some commands such as 'config'. Anyone want to categorically state which version of git is required, and where it can be found for commonly used OS versions?

:: It is highlyrecommended to use v1.5, since it improved much on the user interface side. This is available as git-core in Debian testing and unstable, as well as as backports for etch. The 1.4 which is released with etch should work too, but has some rough edges in the user experience. -- DavidS

First, make sure your Git tool knows who you are, so everyone may shower you with praise.

git config --global --list

user.name=John Doe
user.email=john@example.com
color.diff=auto
color.status=auto
color.branch=auto

If your name and email aren't set properly, you may set them with:

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com

Preparing a patch against puppet:

1 $ git clone git://reductivelabs.com/puppet/
Initialized empty Git repository in /home/david/puppet/puppet/.git/
[...]
  $ cd puppet/
2 $ git checkout -b pending/fix-896 origin/master
3 $ vi README
4 $ git add README
5 $ git commit -m 'improve recommendations about ruby'
Created commit deadc0de: improve recommendations about ruby
 1 files changed, 2 insertions(+), 1 deletions(-)
6 $ git-update-server-info
  $

1. get a copy of the repo
2. create a new branch for the change (Note: please first create a ticket about what you're working on, and name your branch fix-<ticket>, e.g. fix-896 to help Luke merge things back)
3. make changes now
4. notify git of the changes
5. record changes with comment; omit -m to be dropped into a editor
6. help git to access the repo via HTTP

Now you can publish the repo on some webspace or via git-daemon and give out the URL to people who should get the patch. If you want to create multiple independent patches, you can re-checkout from origin/master with new branch names, if one patch depends on another, use the respective branch as starting point. This enables Luke to fetch all your work in one batch, but still work on the various patches independently.

Upon a upstream merge, you can move the corresponding branch away:

  $ git branch -m pending/fix-896 merged/fix-896

or delete it altogether:

  $ git branch -d pending/fix-896

Working with the patch in a local repository:

1 $ git remote add demo_fixes http://www.example.com/puppet-with-README-patch
2 $ git fetch demo_fixes
3 $ git diff demo_fixes/pending/improve-docs..master
4 $ git cherry-pick demo_fixes/pending/improve-docs

1. add a local abbrevation for the published URL
2. fetch changed objects
3. show difference to current master
4. introduce fixed README to local master