Permalink
Browse files

Proof-read the new contributing guide.

Many thanks to Daniele Procida.
  • Loading branch information...
1 parent 23d230f commit 329bb9296f402c6e7d7b648937b72b13a6f5756c @aaugustin aaugustin committed Jun 8, 2012
View
@@ -425,6 +425,7 @@ answer newbie questions, and generally made Django that much better:
polpak@yahoo.com
Ross Poulton <ross@rossp.org>
Mihai Preda <mihai_preda@yahoo.com>
+ Daniele Procida <daniele@vurt.org>
Matthias Pronk <django@masida.nl>
Jyrki Pulliainen <jyrki.pulliainen@gmail.com>
Thejaswi Puthraya <thejaswi.puthraya@gmail.com>
@@ -21,7 +21,7 @@ Partial committers
access to the subsystems that fall under their jurisdiction, and they're
given a formal vote in questions that involve their subsystems. This type
of access is likely to be given to someone who contributes a large
- subframework to Django and wants to continue to maintain it.
+ sub-framework to Django and wants to continue to maintain it.
Partial commit access is granted by the same process as full
committers. However, the bar is set lower; proven expertise in the area
@@ -30,26 +30,28 @@ Partial committers
Decisions on new committers will follow the process explained in
:ref:`how-we-make-decisions`. To request commit access, please contact an
existing committer privately. Public requests for commit access are potential
-flame-war starters, and will be ignored.
+flame-war starters, and will simply be ignored.
Handling pull requests
----------------------
Since Django is now hosted at GitHub, many patches are provided in the form of
-pull requests. When committing a pull request, make sure each individual
-commit matches the commit guidelines described below. Contributors are
-expected to provide the best pull requests possible. However, in practice,
-committers are more familiar with the commit guidelines, and they may have to
-rewrite the commit history.
+pull requests.
+
+When committing a pull request, make sure each individual commit matches the
+commit guidelines described below. Contributors are expected to provide the
+best pull requests possible. In practice however, committers - who will likely
+be more familiar with the commit guidelines - may decide to bring a commit up
+to standard themselves.
Here is one way to commit a pull request::
# Create a new branch tracking upstream/master -- upstream is assumed
# to be django/django.
- git checkout -b pull_xxxx upstream/master
+ git checkout -b pull_xxxxx upstream/master
# Download the patches from github and apply them.
- curl https://github.com/django/django/pull/XXXX.patch | git am
+ curl https://github.com/django/django/pull/xxxxx.patch | git am
At this point, you can work on the code. Use ``git rebase -i`` and ``git
commit --amend`` to make sure the commits have the expected level of quality.
@@ -59,20 +61,20 @@ Once you're ready::
git checkout master
git pull upstream master
# Merge the work as "fast-forward" to master, to avoid a merge commit.
- git merge --ff-only pull_xx
+ git merge --ff-only pull_xxxxx
# Check that only the changes you expect will be pushed to upstream.
git push --dry-run upstream master
# Push!
git push upstream master
- # Get rid of the pull_xxxx branch.
- git branch -d pull_xxxx
+ # Get rid of the pull_xxxxx branch.
+ git branch -d pull_xxxxx
-An alternative is to add the contributor's repository as a new remote, do a
-checkout of the branch and work from there::
+An alternative is to add the contributor's repository as a new remote,
+checkout the branch and work from there::
git remote add <contributor> https://github.com/<contributor>/django.git
- git checkout pull_xxxx <contributor> <contributor's pull request branch>
+ git checkout pull_xxxxx <contributor> <contributor's pull request branch>
At this point, you can work on the code and continue as above.
@@ -151,7 +153,7 @@ Django's Git repository:
review."
* For commits to a branch, prefix the commit message with the branch name.
- For example: "[1.4.x] Fixed #NNNNN -- Added support for mind reading."
+ For example: "[1.4.x] Fixed #xxxxx -- Added support for mind reading."
* Limit commits to the most granular change that makes sense. This means,
use frequent small commits rather than infrequent large commits. For
@@ -165,22 +167,22 @@ Django's Git repository:
<backwards-compatibility-policy>`.
* If your commit closes a ticket in the Django `ticket tracker`_, begin
- your commit message with the text "Fixed #NNNNN", where "NNNNN" is the
+ your commit message with the text "Fixed #xxxxx", where "xxxxx" is the
number of the ticket your commit fixes. Example: "Fixed #123 -- Added
whizbang feature.". We've rigged Trac so that any commit message in that
format will automatically close the referenced ticket and post a comment
to it with the full commit message.
If your commit closes a ticket and is in a branch, use the branch name
- first, then the "Fixed #NNNNN." For example:
+ first, then the "Fixed #xxxxx." For example:
"[1.4.x] Fixed #123 -- Added whizbang feature."
For the curious, we're using a `Trac plugin`_ for this.
.. _Trac plugin: https://github.com/aaugustin/trac-github
* If your commit references a ticket in the Django `ticket tracker`_ but
- does *not* close the ticket, include the phrase "Refs #NNNNN", where "NNNNN"
+ does *not* close the ticket, include the phrase "Refs #xxxxx", where "xxxxx"
is the number of the ticket your commit references. This will automatically
post a comment to the appropriate ticket.
@@ -199,13 +201,14 @@ Django's Git repository:
Reverting commits
-----------------
-Nobody's perfect; mistakes will be committed. When a mistaken commit is
-discovered, please follow these guidelines:
+Nobody's perfect; mistakes will be committed.
+
+But try very hard to ensure that mistakes don't happen. Just because we have a
+reversion policy doesn't relax your responsibility to aim for the highest
+quality possible. Really: double-check your work, or have it checked by
+another committer, **before** you commit it in the first place!
-* Try very hard to ensure that mistakes don't happen. Just because we
- have a reversion policy doesn't relax your responsibility to aim for
- the highest quality possible. Really: double-check your work, or have
- it checked by another committer, before you commit it in the first place!
+When a mistaken commit is discovered, please follow these guidelines:
* If possible, have the original author revert his/her own commit.
@@ -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 <unit-tests>` 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.
Oops, something went wrong.

0 comments on commit 329bb92

Please sign in to comment.