diff --git a/docs/contributing.txt b/docs/contributing.txt index 03670db017..de9236f6c1 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -49,7 +49,7 @@ particular: much information as you possibly can, complete with code snippets, test cases, etc. This means including a clear, concise description of the 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. * **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 it obvious that the ticket includes a patch, and it will add the ticket 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 a regression test to validate the behavior that has been fixed (and prevent - the problem from arising again). - - * If the code associated with a patch adds a new feature, or modifies behavior + the problem from arising again). + + * If the code associated with a patch adds a new feature, or modifies behavior of an existing feature, the patch should also contain documentation. Non-trivial patches @@ -147,19 +147,19 @@ should be considered non-trivial, just ask. 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 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. -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 a patch, create one. 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 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 ticket still isn't getting attention, occasional polite requests for eyeballs @@ -387,21 +387,63 @@ trunk more than once. 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// -Or, if you've got a working directory you'd like to switch to use a branch, -you can use:: +...where ```` is the branch's name. See the `list of branch names`_. + +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// -...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 ``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 =================