Version 14 (modified by 16 years ago) ( diff ) | ,
---|
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 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:
- add the following line to
/etc/apt/sources.list
(substitutingUBUNTU_RELEASE_NAME
with the Ubuntu release you are using):deb http://ppa.launchpad.net/smartlounge/ubuntu UBUNTU_RELEASE_NAME main
- install
git
:$ apt-get update $ apt-get install git
- 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 ¶
- Create a fork of the automatically updated Django SVN trunk mirror on GitHub by clicking fork at http://github.com/django/django/tree/master
- 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.
- Clone the fork to your workstation:
git clone git@github.com:YOUR_NICK_HERE/django.git
- Add the upstream Django SVN mirror for tracking:
cd django git remote add upstream git://github.com/django/django.git git fetch upstream
- Work on code, commit locally as needed:
git commit -a -m "Implemented foo."
- Publish changes to your public repository:
git push
- When the upstream Django SVN mirror is updated, pull the updates from it (fetching and merging in one step):
git pull upstream master
- 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:
- Review the commit list that is listed in the pull request
- 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
- Merge changes with the master branch:
$ git checkout master $ git merge CONTRIBUTOR_NICK_HERE/master
- Run tests
- 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.
- 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). - Pick a task from the lieutenant's GitHub project wiki, update the wiki as needed.
- Clone the fork to your workstation:
git clone git@github.com:YOUR_NICK_HERE/django.git
- 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
- Work on code, commit locally as needed:
git commit -a -m "Implemented foo."
- Publish changes to your public repository:
git push
- When the upstream lieutenant's repository is updated, pull the updates from it:
git pull upstream master
- 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 ¶
- Implement tests for the features to be added
- Commit locally with a descriptive commit message
- Implement the features
- Commit locally
- Run the test suite iteratively, fixing whatever the tests indicate needs fixing
- Commit locally if something changed
- 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:
- Review contributor's changes (knowing that the contributor has assured that tests pass)
- Pull changes from contributor's repo to your repo
- Run the test suite
- Push changes to the public code hosting service
- Update docs if needed