Formatting and sending patches

Using patches for contributions has been deprecated. Please Send a pull requests from a fork instead.

The Deltacloud community works with Git. The process of contributing to the project we prefer contains these steps: local_branch → patch → review → accept → commit process for contributing to the project. This is how the typical workflow used by the core developers looks like:

  1. Set the following settings inside the git configuration file. The config file is located in the root of the Deltacloud project in a hidden .git directory. Open the config file with your preferred editor:

    $ vim deltacloud/.git/config
    

    Add the following information to the configuration file and replace the relevant values with your own ones:

    [sendemail]
    signedoffbycc = no
    chainreplyto = no
    smtpserver = your_smpt.server.address
    thread = yes
    from = your_email_address
    suppresscc = all
    to = dev@deltacloud.apache.org
    
    [core]
    whitespace = trailing-space,space-before-tab
    
  2. Get the latest HEAD of the Deltacloud git repo. You will gain one local branch called master:

    $ git branch
    * master
    
  3. Fetch the latest changes from the git repo:

    $ git pull
    
  4. Create a new local branch for your edits and give it a name:

    $ git checkout -b my_new_branch
    
  5. Make your changes and then check, what you've edited:

    $ git status
    
  6. Commit these changes to your local branch:

    $ git commit -a
    

    This will open an editor (e.g. vi). Enter a commit message. The message should be short and succinct and individual lines shouldn't be longer than 80 characters. See the recent commits with their commit messages to find an inspiration:

    $ git log
    

    When you commit your changes to your local branch, the local branch will be different from your local master branch. Other developers may have already committed their changes to the remote master branch in the Apache git repo in the meantime. Thus, you need to fetch any new changes and merge them into your local master.

  7. Change to master and fetch upstream changes (it there are any):

    $ git checkout master
    $ git pull
    

    Your local master is now up-to-date with the remote master in the git repo.

  8. Rebase the local master onto the branch containing your changes:

    $ git rebase master my_new_branch
    

    This allows you to make patches against master and send them to the Deltacloud mailing list.

    $ git format-patch -o /path/to/where/you/keep/patches/ master
    $ git send-email --compose --subject 'some subject'
      --thread /path/to/where/you/keep/patches/*
    

    The other members of the community will review your patches. The patch has to receive at least one ACK and no NACK to be approved. Then the patch will be committed by one of the Deltacloud developers with commit rights to the Apache repo. If noone is responding to your patch sent to mailing list, feel free to remind yourself after few days.

You can also contribute to the project by reviewing patches sent by other contributors:

  1. Make a new branch where you will apply the patches and test:

    $ git checkout -b jsmith_patches
    
  2. Save the patches to a known location and make sure you're on the right branch . Then apply.

    $ git checkout jsmith_patches
    
    $ cat /path/to/patches/0001-name-of-patch.txt | git apply
    
    or
    $ git am /path/to/patches/0001-name-of-patch.eml
    

    You can use git am ("apply mail") to apply patches in mail format, or git apply for plain-text patches. If you use git apply, you will only apply the patches, whereas git am will also commit the patches to the local branch (preserving the author's commit messages). However, the difference between git am and git apply is insignificant for the purpose of reviewing patches. It depends on whether you want to save the patches as plain-text or in .mbox email format.

  3. If you think the patches are working correctly, send an ACK to the Deltacloud mailing list. Similarly, if you think the patches could cause a problem, send a NACK and explain the issue you have found.

Test the patch Back