Beefed up 'Using branches' part of docs/contributing.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@4203 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Adrian Holovaty 2006-12-14 21:02:30 +00:00
parent fc11b97e97
commit 74a74f3766
1 changed files with 58 additions and 16 deletions

View File

@ -49,7 +49,7 @@ particular:
much information as you possibly can, complete with code snippets, test much information as you possibly can, complete with code snippets, test
cases, etc. This means including a clear, concise description of the cases, etc. This means including a clear, concise description of the
problem, and a clear set of instructions for replicating the problem. problem, and a clear set of instructions for replicating the problem.
A minimal example that illustrates the bug in a nice small test case A minimal example that illustrates the bug in a nice small test case
is the best possible bug report. is the best possible bug report.
* **Don't** use the ticket system to ask support questions. Use the * **Don't** use the ticket system to ask support questions. Use the
@ -125,13 +125,13 @@ Patch style
* Put the prefix "[patch] " before the title of your ticket. This will make * Put the prefix "[patch] " before the title of your ticket. This will make
it obvious that the ticket includes a patch, and it will add the ticket it obvious that the ticket includes a patch, and it will add the ticket
to the `list of tickets with patches`_. to the `list of tickets with patches`_.
* The code required to fix a problem or add a feature is an essential part * 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 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 prevent a regression test to validate the behavior that has been fixed (and prevent
the problem from arising again). the problem from arising again).
* If the code associated with a patch adds a new feature, or modifies behavior * If the code associated with a patch adds a new feature, or modifies behavior
of an existing feature, the patch should also contain documentation. of an existing feature, the patch should also contain documentation.
Non-trivial patches Non-trivial patches
@ -147,19 +147,19 @@ should be considered non-trivial, just ask.
Ticket triage Ticket triage
============= =============
Unfortunately, not all bug reports in the `ticket tracker`_ provide all Unfortunately, not all bug reports in the `ticket tracker`_ provide all
the `required details`_. A number of tickets have patches, but those patches the `required details`_. A number of tickets have patches, but those patches
don't meet all the requirements of a `good patch`_. don't meet all the requirements of a `good patch`_.
One way to help out is to *triage* bugs that have been reported by other users. One way to help out is to *triage* bugs that have been reported by other users.
Pick an open ticket that is missing some details, and try to replicate the Pick an open ticket that is missing some details, and try to replicate the
problem. Fill in the missing pieces of the report. If the ticket doesn't have problem. Fill in the missing pieces of the report. If the ticket doesn't have
a patch, create one. a patch, create one.
Once you've completed all the missing details on the ticket and you have a Once you've completed all the missing details on the ticket and you have a
patch with all the required features, e-mail `django-developers`_. Indicate patch with all the required features, e-mail `django-developers`_. Indicate
that you have triaged a ticket, and recommend a course of action for dealing that you have triaged a ticket, and recommend a course of action for dealing
with that ticket. with that ticket.
At first, this may require you to be persistent. If you find that your triaged At first, this may require you to be persistent. If you find that your triaged
ticket still isn't getting attention, occasional polite requests for eyeballs ticket still isn't getting attention, occasional polite requests for eyeballs
@ -387,21 +387,63 @@ trunk more than once.
Using branches Using branches
-------------- --------------
To test a given branch, you can simply check out the entire branch, like so:: To use a branch, you'll need to do two things:
* Get the branch's code through Subversion.
* Point your Python ``site-packages`` directory at the branch's version of
the ``django`` package rather than the version you already have
installed.
Getting the code from Subversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To get the latest version of a branch's code, check it out using Subversion::
svn co http://code.djangoproject.com/svn/django/branches/<branch>/ svn co http://code.djangoproject.com/svn/django/branches/<branch>/
Or, if you've got a working directory you'd like to switch to use a branch, ...where ``<branch>`` is the branch's name. See the `list of branch names`_.
you can use::
Alternatively, you can automatically convert an existing directory of the
Django source code as long as you've checked it out via Subversion. To do the
conversion, execute this command from within your ``django`` directory::
svn switch http://code.djangoproject.com/svn/django/branches/<branch>/ svn switch http://code.djangoproject.com/svn/django/branches/<branch>/
...in the root of your Django sandbox (the directory that contains ``django``,
``docs``, and ``tests``).
The advantage of using ``svn switch`` instead of ``svn co`` is that the The advantage of using ``svn switch`` instead of ``svn co`` is that the
``switch`` command retains any changes you might have made to your local copy ``switch`` command retains any changes you might have made to your local copy
of the code. It attempts to merge those changes into the "switched" code. of the code. It attempts to merge those changes into the "switched" code. The
disadvantage is that it may cause conflicts with your local changes if the
"switched" code has altered the same lines of code.
(Note that if you use ``svn switch``, you don't need to point Python at the new
version, as explained in the next section.)
.. _list of branch names: http://code.djangoproject.com/browser/django/branches
Pointing Python at the new Django version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once you've retrieved the branch's code, you'll need to change your Python
``site-packages`` directory so that it points to the branch version of the
``django`` directory. (The ``site-packages`` directory is somewhere such as
``/usr/lib/python2.4/site-packages`` or
``/usr/local/lib/python2.4/site-packages`` or ``C:\Python\site-packages``.)
The simplest way to do this is by renaming the old ``django`` directory to
``django.OLD`` and moving the trunk version of the code into the directory
and calling it ``django``.
Alternatively, you can use a symlink called ``django`` that points to the
location of the branch's ``django`` package. If you want to switch back, just
change the symlink to point to the old code.
If you're using Django 0.95 or earlier and installed it using
``python setup.py install``, you'll have a directory called something like
``Django-0.95-py2.4.egg`` instead of ``django``. In this case, edit the file
``setuptools.pth`` and remove the line that references the Django ``.egg``
file. Then copy the branch's version of the ``django`` directory into
``site-packages``.
Official releases Official releases
================= =================