From 329bb9296f402c6e7d7b648937b72b13a6f5756c Mon Sep 17 00:00:00 2001 From: Aymeric Augustin Date: Fri, 8 Jun 2012 11:26:22 +0200 Subject: Proof-read the new contributing guide. Many thanks to Daniele Procida. --- .../writing-code/submitting-patches.txt | 46 ++++-- .../contributing/writing-code/working-with-git.txt | 178 ++++++++++++--------- 2 files changed, 130 insertions(+), 94 deletions(-) (limited to 'docs/internals/contributing/writing-code') diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index 5bd7774cb3..e78eecc23a 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -20,9 +20,10 @@ See the :doc:`working-with-git` for more details on how to use pull requests. In an open-source project with hundreds of contributors around the world, it's important to manage communication efficiently so that work doesn't get -duplicated and contributors can be as effective as possible. Hence, our policy -is for contributors to "claim" tickets in order to let other developers know -that a particular bug or feature is being worked on. +duplicated and contributors can be as effective as possible. + +Hence, our policy is for contributors to "claim" tickets in order to let other +developers know that a particular bug or feature is being worked on. If you have identified a contribution you want to make and you're capable of fixing it (as measured by your coding ability, knowledge of Django internals @@ -68,18 +69,23 @@ no longer monopolized and somebody else can claim it. If you've claimed a ticket and it's taking a long time (days or weeks) to code, keep everybody updated by posting comments on the ticket. If you don't provide regular updates, and you don't respond to a request for a progress report, -your claim on the ticket may be revoked. As always, more communication is -better than less communication! +your claim on the ticket may be revoked. + +As always, more communication is better than less communication! Which tickets should be claimed? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Of course, going through the steps of claiming tickets is overkill in some -cases. In the case of small changes, such as typos in the documentation or +cases. + +In the case of small changes, such as typos in the documentation or small bugs that will only take a few minutes to fix, you don't need to jump through the hoops of claiming tickets. Just submit your patch and be done with -it. Of course, it is always acceptable, regardless of the ticket's ownership -status, to submit patches to a ticket if you happen to have a patch ready. +it. + +Of course, it is *always* acceptable, regardless whether someone has claimed it +or not, to submit patches to a ticket if you happen to have a patch ready. .. _patch-style: @@ -90,12 +96,12 @@ Make sure that any contribution you do fulfills at least the following requirements: * The code required to fix a problem or add a feature is an essential part - of a patch, but it is not the only part. A good patch should also - include a regression test to validate the behavior that has been fixed - and to prevent the problem from arising again. Also, if some tickets are - relevant to the code that you've written, mention the ticket numbers in + of a patch, but it is not the only part. A good patch should also include a + :doc:`regression test ` to validate the behavior that has been + fixed and to prevent the problem from arising again. Also, if some tickets + are relevant to the code that you've written, mention the ticket numbers in some comments in the test so that one can easily trace back the relevant - discussions after your patch gets committed and the tickets get closed. + discussions after your patch gets committed, and the tickets get closed. * If the code associated with a patch adds a new feature, or modifies behavior of an existing feature, the patch should also contain @@ -105,6 +111,7 @@ You can use either GitHub branches and pull requests or direct patches to publish your work. If you use the Git workflow, then you should announce your branch in the ticket by including a link to your branch. When you think your work is ready to be merged in create a pull request. + See the :doc:`working-with-git` documentation for mode details. You can also use patches in Trac. When using this style, follow these @@ -139,8 +146,10 @@ A "non-trivial" patch is one that is more than a simple bug fix. It's a patch that introduces Django functionality and makes some sort of design decision. If you provide a non-trivial patch, include evidence that alternatives have -been discussed on `django-developers`_. If you're not sure whether your patch -should be considered non-trivial, just ask. +been discussed on `django-developers`_. + +If you're not sure whether your patch should be considered non-trivial, just +ask. Javascript patches ------------------ @@ -156,6 +165,9 @@ code for future development (e.g. ``foo.js``), and a compressed version for production use (e.g. ``foo.min.js``). Any links to the file in the codebase should point to the compressed version. +Compressing JavaScript +~~~~~~~~~~~~~~~~~~~~~~ + To simplify the process of providing optimized javascript code, Django includes a handy script which should be used to create a "minified" version. This script is located at ``django/contrib/admin/static/js/compress.py``. @@ -167,11 +179,11 @@ complete javascript patches will need to download and install the library independently. The Closure Compiler library requires Java version 6 or higher (Java 1.6 or -higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with +higher on Mac OS X. Note that Mac OS X 10.5 and earlier did not ship with Java 1.6 by default, so it may be necessary to upgrade your Java installation before the tool will be functional. Also note that even after upgrading Java, the default ``/usr/bin/java`` command may remain linked to the previous Java -binary, so relinking that command may be necessary as well. +binary, so relinking that command may be necessary as well.) Please don't forget to run ``compress.py`` and include the ``diff`` of the minified scripts when submitting patches for Django's javascript. diff --git a/docs/internals/contributing/writing-code/working-with-git.txt b/docs/internals/contributing/writing-code/working-with-git.txt index dee9b9e074..ad03a29860 100644 --- a/docs/internals/contributing/writing-code/working-with-git.txt +++ b/docs/internals/contributing/writing-code/working-with-git.txt @@ -11,18 +11,20 @@ that you also work using GitHub. After installing Git the first thing you should do is setup your name and email:: - $ git config --global user.name "Firstname Lastname" - $ git config --global user.email "your_email@youremail.com" + $ git config --global user.name "Your Real Name" + $ git config --global user.email "you@email.com" Note that ``user.name`` should be your real name, not your GitHub nick. GitHub should know the email you use in the ``user.email`` field, as this will be used to associate your commits with your GitHub account. Now we are going to show how to create a GitHub pull request containing the -changes for Trac ticket #xxxxx. By creating a fully ready pull request you -will make the committers' job easier, and thus your work is more likely to be -merged into Django. You can also upload a traditional patch to Trac, but it's -less practical for reviews. +changes for Trac ticket #xxxxx. By creating a fully-ready pull request you +will make the committers' job easier, meaning that your work is more likely to +be merged into Django. + +You could also upload a traditional patch to Trac, but it's less practical for +reviews. .. _Git: http://git-scm.com/ .. _GitHub: https://github.com/ @@ -31,14 +33,18 @@ less practical for reviews. Setting up local repository --------------------------- -When you have created a GitHub account, with the nick "github_nick", and -forked Django's repository, you should create a local copy of your fork:: +When you have created your GitHub account, with the nick "github_nick", and +forked Django's repository, create a local copy of your fork:: git clone git@github.com:github_nick/django.git -This will create a new directory "django" containing a clone of your GitHub -repository. Your GitHub repository will be called "origin" in Git. You should -also setup django/django as an "upstream" remote:: +This will create a new directory "django", containing a clone of your GitHub +repository. + +Your GitHub repository will be called "origin" in Git. + +You should also setup django/django as an "upstream" remote (that is, tell git +that the reference Django repository was the source of your fork of it):: git remote add upstream git@github.com:django/django.git git fetch upstream @@ -50,12 +56,15 @@ You can add other remotes similarly, for example:: Working on a ticket ------------------- -When working on a ticket you will almost always want to create a new branch -for the work, and base that work on upstream/master:: +When working on a ticket create a new branch for the work, and base that work +on upstream/master:: git checkout -b ticket_xxxxx upstream/master -If you are working for a fix on the 1.4 branch, you would instead do:: +The -b flag creates a new branch for you locally. Don't hesitate to create new +branches even for the smallest things - that's what they are there for. + +If instead you were working for a fix on the 1.4 branch, you would do:: git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x @@ -64,7 +73,7 @@ commit them:: git commit -When writing the commit message, you should follow the :ref:`commit message +When writing the commit message, follow the :ref:`commit message guidelines ` to ease the work of the committer. If you're uncomfortable with English, try at least to describe precisely what the commit does. @@ -77,69 +86,77 @@ necessary:: Publishing work ~~~~~~~~~~~~~~~ -You can publish your work on GitHub by just using:: +You can publish your work on GitHub just by doing:: git push origin ticket_xxxxx When you go to your GitHub page you will notice a new branch has been created. + If you are working on a Trac ticket, you should mention in the ticket that your work is available from branch ticket_xxxxx of your github repo. Include a link to your branch. -Note that the above branch is called a "topic branch" in Git parlance. This -means that other people should not base their work on your branch. In -particular this means you are free to rewrite the history of this branch (by -using ``git rebase`` for example). There are also "public branches". These are -branches other people are supposed to fork, and thus their history should -never change. Good examples of public branches are the ``master`` and -``stable/A.B.x`` branches in the django/django repository. +Note that the above branch is called a "topic branch" in Git parlance. You are +free to rewrite the history of this branch, by using ``git rebase`` for +example. Other people shouldn't base their work on such a branch, because +their clone would become corrupt when you edit commits. + +There are also "public branches". These are branches other people are supposed +to fork, so the history of these branches should never change. Good examples +of public branches are the ``master`` and ``stable/A.B.x`` branches in the +django/django repository. When you think your work is ready to be pulled into Django, you should create -a pull request at GitHub. A good pull request contains: +a pull request at GitHub. A good pull request means: -* Commits with one logical change in each, following the - :doc:`coding style `. +* commits with one logical change in each, following the + :doc:`coding style `, -* Well formed messages for each commit: a summary line and then paragraphs - wrapped at 72 characters thereafter. See the :ref:`committing guidelines - ` for more details. +* well-formed messages for each commit: a summary line and then paragraphs + wrapped at 72 characters thereafter -- see the :ref:`committing guidelines + ` for more details, -* Documentation and tests, if needed. Actually tests are always needed, except - for documentation changes. +* documentation and tests, if needed -- actually tests are always needed, + except for documentation changes. -* The test suite passes and the documentation builds without warnings. +The test suite must pass and the documentation must build without warnings. Once you have created your pull request, you should add a comment in the -related Trac ticket explaining what you've done. In particular you should tell -in which environment you've run the tests, for instance: "all tests pass under -SQLite and MySQL". +related Trac ticket explaining what you've done. In particular you should note +the environment in which you ran the tests, for instance: "all tests pass +under SQLite and MySQL". -Your pull request should be ready for merging into Django. Pull requests at -GitHub have only two states: open and closed. The committers who deals with -your pull request has only two options: merge it or close it. For this reason, -it isn't useful to make a pull request until the code is ready for merging -- -or sufficiently close that a committer will finish it himself. +Pull requests at GitHub have only two states: open and closed. The committer +who will deal with your pull request has only two options: merge it or close +it. For this reason, it isn't useful to make a pull request until the code is +ready for merging -- or sufficiently close that a committer will finish it +himself. Rebasing branches ~~~~~~~~~~~~~~~~~ In the example above you created two commits, the "Fixed ticket_xxxxx" commit -and "Added two more tests" commit. We do not want to have the "Added two more -tests" commit in the Django's repository as it would just be useless noise. -Instead, we would like to only have one commit. To rework the history of your -branch you can squash the commits into one by using interactive rebase:: +and "Added two more tests" commit. + +We do not want to have the entire history of your working process in your +repository. Your commit "Added two more tests" would be unhelpful noise. +Instead, we would rather only have one commit containing all your work. + +To rework the history of your branch you can squash the commits into one by +using interactive rebase:: git rebase -i HEAD~2 The HEAD~2 above is shorthand for two latest commits. The above command will open an editor showing the two commits, prefixed with the word "pick". -You should change the second line to "squash" instead. This will keep the -first commit, and squash the second commit to the first one. Save and quit -the editor. A second editor window should open. Here you can reword the -commit message for the commit. + +Change the second line to "squash" instead. This will keep the +first commit, and squash the second commit into the first one. Save and quit +the editor. A second editor window should open, so you can reword the +commit message for the commit now that it includes both your steps. You can also use the "edit" option in rebase. This way you can change a single -commit. For example:: +commit, for example to fix a typo in a docstring:: git rebase -i HEAD~3 # Choose edit, pick, pick for the commits @@ -148,17 +165,18 @@ commit. For example:: git commit --amend # reword the commit message if needed git rebase --continue - # The second and third commit should be applied. + # The second and third commits should be applied. -If you need to change an already published topic branch at GitHub, you will -need to force-push the changes:: +If your topic branch is already published at GitHub, for example if you're +making minor changes to take into account a review, you will need to force- +push the changes:: git push -f origin ticket_xxxxx Note that this will rewrite history of ticket_xxxxx - if you check the commit hashes before and after the operation at GitHub you will notice that the -commit hashes do not match any more. This is acceptable, as the branch is topic -branch, and nobody should be basing their work on this branch. +commit hashes do not match any more. This is acceptable, as the branch is merely +a topic branch, and nobody should be basing their work on it. After upstream has changed ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -173,16 +191,18 @@ The work is automatically rebased using the branch you forked on, in the example case using upstream/master. The rebase command removes all your local commits temporarily, applies the -upstream commits, and then applies your local commits again on the work. If -there are merge conflicts you will need to resolve them and then use ``git +upstream commits, and then applies your local commits again on the work. + +If there are merge conflicts you will need to resolve them and then use ``git rebase --continue``. At any point you can use ``git rebase --abort`` to return to the original state. -Note that you want to rebase on upstream, not merge the upstream. The reason -for this is that by rebasing, your commits will always be on top of the -upstream's work, not mixed with the changes in the upstream. This way your -branch only contains commits related to its topic, and this makes squashing -easier. +Note that you want to *rebase* on upstream, not *merge* the upstream. + +The reason for this is that by rebasing, your commits will always be *on +top of* the upstream's work, not *mixed in with* the changes in the upstream. +This way your branch will contain only commits related to its topic, which +makes squashing easier. After review ------------ @@ -190,31 +210,35 @@ After review It is unusual to get any non-trivial amount of code into core without changes requested by reviewers. In this case, it is often a good idea to add the changes as one incremental commit to your work. This allows the reviewer to -easily check what changes you have done:: +easily check what changes you have done. - # Do changes required by the reviewer, commit often. - # Before publishing the changes, rebase your work. Assume you added two - # commits to the work. - git rebase -i HEAD~2 - # squash the second commit into the first, write a commit message something - # like this: - Made changes asked in review by the_reviewer +In this case, do the changes required by the reviewer. Commit as often as +necessary. Before publishing the changes, rebase your work. If you added two +commits, you would run:: - - Fixed whitespace errors in foo/bar - - Reworded the doc string of the_method() + git rebase -i HEAD~2 - # Push your work back to your github repo, there should not be any need - # for force (-f) push, as you didn't touch the public commits in the rebase. - git push origin ticket_xxxxx - # Check your pull request, it should now contain the new commit, too. +Squash the second commit into the first. Write a commit message along the lines of:: + + Made changes asked in review by + + - Fixed whitespace errors in foobar + - Reworded the docstring of bar() + +Finally push your work back to your GitHub repository. Since you didn't touch +the public commits during the rebase, you should not need to force-push:: + + git push origin ticket_xxxxx + +Your pull request should now contain the new commit too. -The committer is likely to squash the review commit into the previous commit +Note that the committer is likely to squash the review commit into the previous commit when committing the code. Summary ------- -* Work on GitHub if possible. +* Work on GitHub if you can. * Announce your work on the Trac ticket by linking to your GitHub branch. * When you have something ready, make a pull request. * Make your pull requests as good as you can. -- cgit v1.3