[[PageOutline]]

= Collaboration on !GitHub =

This page gives guidelines for distributed Django development.

'''It is not part of the official 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 can pick them 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 commit list that is listed in the pull request
 1. If everything looks good, pull code from the the contributor's repository (this creates a new branch, if the branch already exists, skip the `remote add` step): 
 {{{
$ git remote add -f CONTRIBUTOR_NICK_HERE git://github.com/CONTRIBUTOR_NICK_HERE/django.git
$ git checkout -b CONTRIBUTOR_NICK_HERE/master
$ git pull CONTRIBUTOR_NICK_HERE master # for current or master:XXXXXXX, where XXXXXX is the changeset code received in pull request 
 }}}
 1. Merge changes with the master branch:
 {{{
$ git checkout master
$ git merge CONTRIBUTOR_NICK_HERE/master
 }}}
 1. Run tests
 1. If tests pass, push changes to your public repository:
 {{{
$ git push
 }}}

=== 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.

== Quality assurance ==

To assure that the contribution is in par with Django code quality standards, the actual development workflow should be similar to the following:

=== Contributor ===

 1. Implement tests for the features to be added
 1. Commit locally with a descriptive commit message
 1. Implement the features
 1. Commit locally
 1. Run the test suite iteratively, fixing whatever the tests indicate needs fixing
 1. Commit locally if something changed
 1. Push your changes to !GitHub

=== Lieutenant ===

Specify the API and design of the feature on !GitHub wiki, try to add documentation that specifies the behaviour '''before''' implementation.

Integrating contributor's work:

 1. Review contributor's changes (knowing that the contributor has assured that tests pass)
 1. Pull changes from contributor's repo to your repo
 1. Run the test suite
 1. Push changes to the public code hosting service 
 1. Update docs if needed