= Collaboration on !GitHub =

This page gives guidelines for distributed Django development. It is not officially part of the Django development process.

== Prerequisites ==

=== 1. Install git ===

If you want to learn more about `git`, see [http://git-scm.com/ the git webpage] or [http://git.or.cz/gitwiki/GitCheatSheet the git cheat sheet] for a quick overview.

==== Ubuntu ====

As of January 2009, the latest `git` release is 1.6.1. As there are many improvements compared with older releases (notably, a single executable), it is advisable to use this version instead of the ones provided in the Ubuntu release repositories. There is [https://launchpad.net/~smartlounge/+archive a personal package archive] that provides `git` 1.6.1 backports to all Ubuntu releases since Hardy.

Installation instructions:  
 1. add the following line to `/etc/apt/sources.list` (substituting `UBUNTU_RELEASE_NAME` with the Ubuntu release you are using):
 {{{
deb http://ppa.launchpad.net/smartlounge/ubuntu UBUNTU_RELEASE_NAME main
 }}}
 1. install `git`:
 {{{
$ apt-get update
$ apt-get install git
 }}}
 1. verify that the correct version was installed:
 {{{
$ git --version
git version 1.6.1
 }}}

=== 2. Register an account on !GitHub ===

Go to https://github.com/signup/free and follow the instructions.

== Work process ==

The process should be managed with the '''Dictator and Lieutenants Workflow''', described at http://whygitisbetterthanx.com/#any-workflow.
 * ''Dictators'' are core Django developers, who eventually merge the `git` branches back to Django trunk.
 * ''Lieutenants'' are developers, who take the responsibility of steering and coordinating the work on a large feature (e.g. aggregates).
 * ''Contributors'' are developers who contribute -- under lieutenant's guidance -- to the development of the feature.

=== Lieutenant ===

 1. Create a fork of the automatically updated Django SVN trunk mirror on !GitHub by clicking ''fork'' at http://github.com/django/django/tree/master
 1. Describe the design of the feature you implement on the !GitHub project wiki, list tasks that need tackling so that contributors get a clear overview and can pick tasks easily.
 1. Clone the fork to your workstation:
 {{{
git clone git@github.com:YOUR_NICK_HERE/django.git
 }}}
 1. Add the upstream Django SVN mirror for tracking:
 {{{
cd django
git remote add upstream git://github.com/django/django.git
git fetch upstream
 }}}
 1. Work on code, commit locally as needed:
 {{{
git commit -a -m "Implemented foo."
 }}}
 1. Publish changes to your public repository:
 {{{
git push
 }}}
 1. When the upstream Django SVN mirror is updated, pull the updates from it (fetching and merging in one step): 
 {{{
git pull upstream master
 }}}
 1. When the feature is ready, get in contact with a core developer (the ''dictator'') to integrate your work.

==== Managing contributor submissions ====

When a contributor feels that his updates are ready to be merged back to lieutenant's repository, he should submit a '''pull request''' to the lieutenant (see below).

When a lieutenant receives a pull request: 
 1. Review the diff with !GitHub web tools

=== Contributor ===

Largely, this is a copy-paste of the lieutenant workflow, only the tracked repositories and the final step (pull request) differ.

 1. Create a fork of the lieutenant's repository on !GitHub by clicking ''fork'' at e.g. http://github.com/LIEUTENANT_NICK_HERE/django/tree/master (the URL may differ, obviously, LIEUTENANT_NICK_HERE is just a placeholder).
 1. Pick a task from the lieutenant's !GitHub project wiki, update the wiki as needed.
 1. Clone the fork to your workstation:
 {{{
git clone git@github.com:YOUR_NICK_HERE/django.git
 }}}
 1. Add the upstream lieutenant's repository for tracking:
 {{{
cd django
git remote add upstream git://github.com/LIEUTENANT_NICK_HERE/django.git
git fetch upstream
 }}}
 1. Work on code, commit locally as needed:
 {{{
git commit -a -m "Implemented foo."
 }}}
 1. Publish changes to your public repository:
 {{{
git push
 }}}
 1. When the upstream lieutenant's repository is updated, pull the updates from it: 
 {{{
git pull upstream master
 }}}
 1. When the feature is ready, send the lieutenant a pull request by clicking ''pull request'' on your forked project's page.