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 ​the git webpage or ​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 ​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
   

2. install git:

   $ apt-get update
   $ apt-get install git
   

3. 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
2. 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.
3. Clone the fork to your workstation:

   git clone git@github.com:YOUR_NICK_HERE/django.git
   

4. Add the upstream Django SVN mirror for tracking:

   cd django
   git remote add upstream git://github.com/django/django.git
   git fetch upstream
   

5. Work on code, commit locally as needed:

   git commit -a -m "Implemented foo."
   

6. Publish changes to your public repository:

   git push
   

7. When the upstream Django SVN mirror is updated, pull the updates from it (fetching and merging in one step):

   git pull upstream master
   

8. 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).
2. Pick a task from the lieutenant's GitHub project wiki, update the wiki as needed.
3. Clone the fork to your workstation:

   git clone git@github.com:YOUR_NICK_HERE/django.git
   

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

5. Work on code, commit locally as needed:

   git commit -a -m "Implemented foo."
   

6. Publish changes to your public repository:

   git push
   

7. When the upstream lieutenant's repository is updated, pull the updates from it:

   git pull upstream master
   

8. When the feature is ready, send the lieutenant a pull request by clicking pull request on your forked project's page.