Last updated by ldaley 2 years ago
Most Grails-related source is hosted on GitHub, including the core source code, the functional test suite, and the source for the user guide. If you want to provide patches for any of these projects, then you should use git to generate them.

Getting hold of git

Before you can use git, you need to install it on your computer. This step is of course platform-dependent, but a few suggestions for some common operating systems follow.

Windows

Download and run the msysgit installer. This will provide a shortcut from which you can start a command prompt dedicated to git. Once running, you execute git as you would for any other OS.

Mac OS X

You have a couple of options. You can grab the dmg package or use MacPorts:

sudo port install git-core +svn+bash_completion

This will allow you work against Subversion repositories (via git svn ) and give you bash completion.

Linux

You can get RPM and Debian packages from the git download site, but it's usually easier to use apt-get or yum :

sudo apt-get install git-core
# or
su -c 'yum install git-core'

Once you have git installed, you can fetch the source you want to work on from GitHub.

Cloning the repository

If you just want to create a patch for a project, then all you need is a read-only clone of the relevant project. You can find the URLs on the GitHub pages for each project. The HTTP URL is recommended since it works with HTTP proxies. So, let's take the Grails core project as an example:

git clone http://github.com/grails/grails-core.git

The above command will create a new directory called "grails-core" and populate it with a clone of the project source. You won't be able to push changes back to the remote repository on GitHub, but that's not what we're trying to do.

Creating a patch

Before you start hacking away and making changes to the code, wait! It's often a good idea to work on local branches. So, once you've cloned the repository, run this from within the project directory: 

git checkout -b myChanges
This will create a local branch called "myChanges" and switch your working copy to it. You can now hack away to your heart's content!

Once you have committed the changes that you want to your local branch, it's time to create the patch. First, make sure you're synchronised with the latest code: 

git checkout master
git pull
git checkout myChanges
git rebase master
Your local branch will now have the latest code from the master branch. For the next step, you have a couple of options. If you have created only one commit, then you can run: 
git format-patch -1
This will generate a file in the current directory with the name "001-*.patch" that you can attach to a JIRA issue (you may have to create one first).

On the other hand, if you have more than one commit you can generate patch files for them in one go. Simply execute git log and find the commit immediately preceding the first one you want to generate a patch for. You can then run: 

git format-patch <commit ID>
All commits in git are identified by a long hash like 8b0e042a7523558244ea1ac405e145c859ef0370. It look scary, but copy & paste is your friend! And that's how you generate a patch.

Considerations

Whitespace

Please ensure that any new code is formatted with 4 space characters as the indent.

Minimising Changes

To make it easier for the patch to be reviewed, please attempt to minimise the changes made to be the necessary changes to affect the issue you are addressing. For example, do not reformat unrelated code in the same patch as a fix for a bug. Likewise, if you discover another bug/issue/sub-optimal section of code while addressing another issue and wish to change that as well, please submit it as another patch.