--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/thirdparty/google_appengine/lib/django/docs/contributing.txt Tue Aug 26 21:49:54 2008 +0000
@@ -0,0 +1,654 @@
+======================
+Contributing to Django
+======================
+
+If you think working *with* Django is fun, wait until you start working *on* it.
+We're passionate about helping Django users make the jump to contributing members
+of the community, so there are many ways you can help Django's development:
+
+ * Blog about Django. We syndicate all the Django blogs we know about on
+ the `community page`_; contact jacob@jacobian.org if you've got a blog
+ you'd like to see on that page.
+
+ * Report bugs and request features in our `ticket tracker`_. Please read
+ `Reporting bugs`_, below, for the details on how we like our bug reports
+ served up.
+
+ * Submit patches for new and/or fixed behavior. Please read `Submitting
+ patches`_, below, for details on how to submit a patch.
+
+ * Join the `django-developers`_ mailing list and share your ideas for how
+ to improve Django. We're always open to suggestions, although we're
+ likely to be skeptical of large-scale suggestions without some code to
+ back it up.
+
+ * Triage patches that have been submitted by other users. Please read
+ `Ticket triage`_ below, for details on the triage process.
+
+That's all you need to know if you'd like to join the Django development
+community. The rest of this document describes the details of how our community
+works and how it handles bugs, mailing lists, and all the other minutiae of
+Django development.
+
+Reporting bugs
+==============
+
+Well-written bug reports are *incredibly* helpful. However, there's a certain
+amount of overhead involved in working with any bug tracking system, so your
+help in keeping our ticket tracker as useful as possible is appreciated. In
+particular:
+
+ * **Do** read the FAQ_ to see if your issue might be a well-known question.
+
+ * **Do** `search the tracker`_ to see if your issue has already been filed.
+
+ * **Do** ask on `django-users`_ *first* if you're not sure if what you're
+ seeing is a bug.
+
+ * **Do** write complete, reproducible, specific bug reports. Include as
+ 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
+ is the best possible bug report.
+
+ * **Don't** use the ticket system to ask support questions. Use the
+ `django-users`_ list, or the `#django`_ IRC channel for that.
+
+ * **Don't** use the ticket system to make large-scale feature requests.
+ We like to discuss any big changes to Django's core on the `django-developers`_
+ list before actually working on them.
+
+ * **Don't** reopen issues that have been marked "wontfix". This mark means
+ that the decision has been made that we can't or won't fix this particular
+ issue. If you're not sure why, please ask on `django-developers`_.
+
+ * **Don't** use the ticket tracker for lengthy discussions, because they're
+ likely to get lost. If a particular ticket is controversial, please move
+ discussion to `django-developers`_.
+
+Reporting security issues
+=========================
+
+Report security issues to security@djangoproject.com. This is a private list
+only open to long-time, highly trusted Django developers, and its archives are
+not publicly readable.
+
+In the event of a confirmed vulnerability in Django itself, we will take the
+following actions:
+
+ * Acknowledge to the reporter that we've received the report and that a fix
+ is forthcoming. We'll give a rough timeline and ask the reporter to keep
+ the issue confidential until we announce it.
+
+ * Halt all other development as long as is needed to develop a fix, including
+ patches against the current and two previous releases.
+
+ * Determine a go-public date for announcing the vulnerability and the fix.
+ To try to mitigate a possible "arms race" between those applying the patch
+ and those trying to exploit the hole, we will not announce security
+ problems immediately.
+
+ * Pre-notify everyone we know to be running the affected version(s) of
+ Django. We will send these notifications through private e-mail which will
+ include documentation of the vulnerability, links to the relevant patch(es),
+ and a request to keep the vulnerability confidential until the official
+ go-public date.
+
+ * Publicly announce the vulnerability and the fix on the pre-determined
+ go-public date. This will probably mean a new release of Django, but
+ in some cases it may simply be patches against current releases.
+
+Submitting patches
+==================
+
+We're always grateful for patches to Django's code. Indeed, bug reports with
+associated patches will get fixed *far* more quickly than those without patches.
+
+Patch style
+-----------
+
+ * Make sure your code matches our `coding style`_.
+
+ * Submit patches in the format returned by the ``svn diff`` command.
+ An exception is for code changes that are described more clearly in plain
+ English than in code. Indentation is the most common example; it's hard to
+ read patches when the only difference in code is that it's indented.
+
+ * Attach patches to a ticket in the `ticket tracker`_, using the "attach file"
+ button. Please *don't* put the patch in the ticket description or comment
+ unless it's a single line patch.
+
+ * Name the patch file with a ``.diff`` extension; this will let the ticket
+ tracker apply correct syntax highlighting, which is quite helpful.
+
+ * Check the "Has patch" box on the ticket details. 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
+ 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
+ of an existing feature, the patch should also contain documentation.
+
+Non-trivial patches
+-------------------
+
+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.
+
+Ticket triage
+=============
+
+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. A couple of dedicated volunteers work on this regularly, but more help
+is always appreciated.
+
+Most of the workflow is based around the concept of a ticket's "triage stage".
+This stage describes where in its lifetime a given ticket is at any time.
+Along with a handful of flags, this field easily tells us what and who each
+ticket is waiting on.
+
+Since a picture is worth a thousand words, let's start there:
+
+.. image:: http://media.djangoproject.com/img/doc/djangotickets.png
+ :height: 451
+ :width: 590
+ :alt: Django's ticket workflow
+
+We've got two roles here:
+
+ * Core developers: people with commit access who make the decisions and
+ write the bulk of the code.
+
+ * Ticket triagers: community members who keep track of tickets, making
+ sure the tickets are always categorized correctly.
+
+Second, note the four triage stages:
+
+ 1. A ticket starts as "Unreviewed", meaning that a triager has yet to
+ examine the ticket and move it along.
+
+ 2. "Design decision needed" means "this concept requires a design
+ decision," which should be discussed either in the ticket comments or on
+ django-developers.
+
+ 3. Once a ticket is ruled to be approved for fixing, it's moved into the
+ "Accepted" stage. This stage is where all the real work gets done.
+
+ 4. If a ticket has an associated patch (see below), a triager will review the
+ patch. If the patch is complete, it'll be marked as "ready for checkin" so
+ that a core developer knows to review and check in the patches.
+
+The second part of this workflow involves a set of flags the describe what the
+ticket has or needs in order to be "ready for checkin":
+
+ "Has patch"
+ This means the ticket has an associated patch_. These will be
+ reviewed to see if the patch is "good".
+
+ "Needs documentation"
+ This flag is used for tickets with patches that need associated
+ documentation. Complete documentation of features is a prerequisite
+ before we can check a fix into the codebase.
+
+ "Needs tests"
+ This flags the patch as needing associated unit tests. Again, this is a
+ required part of a valid patch.
+
+ "Patch needs improvement"
+ This flag means that although the ticket *has* a patch, it's not quite
+ ready for checkin. This could mean the patch no longer applies
+ cleanly, or that the code doesn't live up to our standards.
+
+A ticket can be resolved in a number of ways:
+
+ "fixed"
+ Used by one of the core developers once a patch has been rolled into
+ Django and the issue is fixed.
+
+ "invalid"
+ Used if the ticket is found to be incorrect or a user error.
+
+ "wontfix"
+ Used when a core developer decides that this request is not
+ appropriate for consideration in Django. This is usually chosen after
+ discussion in the ``django-developers`` mailing list, and you should
+ feel free to join in when it's something you care about.
+
+ "duplicate"
+ Used when another ticket covers the same issue. By closing duplicate
+ tickets, we keep all the discussion in one place, which helps everyone.
+
+ "worksforme"
+ Used when the triage team is unable to replicate the original bug.
+
+If you believe that the ticket was closed in error -- because you're
+still having the issue, or it's popped up somewhere else, or the triagers have
+-- made a mistake, please reopen the ticket and tell us why. Please do not
+reopen tickets that have been marked as "wontfix" by core developers.
+
+.. _required details: `Reporting bugs`_
+.. _good patch: `Patch style`_
+.. _patch: `Submitting patches`_
+
+Submitting and maintaining translations
+=======================================
+
+Various parts of Django, such as the admin site and validator error messages,
+are internationalized. This means they display different text depending on a
+user's language setting.
+
+These translations are contributed by Django users worldwide. If you find an
+incorrect translation, or if you'd like to add a language that isn't yet
+translated, here's what to do:
+
+ * Join the `Django i18n mailing list`_ and introduce yourself.
+ * Create and submit translations using the methods described in the
+ `i18n documentation`_.
+
+.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
+.. _i18n documentation: ../i18n/
+
+Coding style
+============
+
+Please follow these coding standards when writing code for inclusion in Django:
+
+ * Unless otherwise specified, follow `PEP 8`_.
+
+ * Use four spaces for indentation.
+
+ * Use underscores, not camelCase, for variable, function and method names
+ (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``).
+
+ * Use ``InitialCaps`` for class names (or for factory functions that
+ return classes).
+
+ * Mark all strings for internationalization; see the `i18n documentation`_
+ for details.
+
+ * In Django template code, put one (and only one) space between the curly
+ brackets and the tag contents.
+
+ Do this::
+
+ {{ foo }}
+
+ Don't do this::
+
+ {{foo}}
+
+ * In Django views, the first parameter in a view function should be called
+ ``request``.
+
+ Do this::
+
+ def my_view(request, foo):
+ # ...
+
+ Don't do this::
+
+ def my_view(req, foo):
+ # ...
+
+ * Please don't put your name in the code you contribute. Our policy is to
+ keep contributors' names in the ``AUTHORS`` file distributed with Django
+ -- not scattered throughout the codebase itself. Feel free to include a
+ change to the ``AUTHORS`` file in your patch if you make more than a
+ single trivial change.
+
+Committing code
+===============
+
+Please follow these guidelines when committing code to Django's Subversion
+repository:
+
+ * For any medium-to-big changes, where "medium-to-big" is according to your
+ judgment, please bring things up on the `django-developers`_ mailing list
+ before making the change.
+
+ If you bring something up on `django-developers`_ and nobody responds,
+ please don't take that to mean your idea is great and should be
+ implemented immediately because nobody contested it. Django's lead
+ developers don't have a lot of time to read mailing-list discussions
+ immediately, so you may have to wait a couple of days before getting a
+ response.
+
+ * Write detailed commit messages in the past tense, not present tense.
+
+ * Good: "Fixed Unicode bug in RSS API."
+ * Bad: "Fixes Unicode bug in RSS API."
+ * Bad: "Fixing Unicode bug in RSS API."
+
+ * For commits to a branch, prefix the commit message with the branch name.
+ For example: "magic-removal: 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
+ example, if implementing feature X requires a small change to library Y,
+ first commit the change to library Y, then commit feature X in a separate
+ commit. This goes a *long way* in helping all core Django developers
+ follow your changes.
+
+ * If your commit closes a ticket in the Django `ticket tracker`_, begin
+ your commit message with the text "Fixed #abc", where "abc" is the number
+ of the ticket your commit fixes. Example: "Fixed #123 -- Added support
+ for foo". We've rigged Subversion and 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 #abc." For example:
+ "magic-removal: Fixed #123 -- Added whizbang feature."
+
+ For the curious: We're using a `Trac post-commit hook`_ for this.
+
+ .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
+
+ * If your commit references a ticket in the Django `ticket tracker`_ but
+ does *not* close the ticket, include the phrase "Refs #abc", where "abc"
+ is the number of the ticket your commit references. We've rigged
+ Subversion and Trac so that any commit message in that format will
+ automatically post a comment to the appropriate ticket.
+
+Unit tests
+==========
+
+Django comes with a test suite of its own, in the ``tests`` directory of the
+Django tarball. It's our policy to make sure all tests pass at all times.
+
+The tests cover:
+
+ * Models and the database API (``tests/modeltests/``).
+ * The cache system (``tests/regressiontests/cache.py``).
+ * The ``django.utils.dateformat`` module (``tests/regressiontests/dateformat/``).
+ * Database typecasts (``tests/regressiontests/db_typecasts/``).
+ * The template system (``tests/regressiontests/templates/`` and
+ ``tests/regressiontests/defaultfilters/``).
+ * ``QueryDict`` objects (``tests/regressiontests/httpwrappers/``).
+ * Markup template tags (``tests/regressiontests/markup/``).
+
+We appreciate any and all contributions to the test suite!
+
+The Django tests all use the testing infrastructure that ships with Django for
+testing applications. See `Testing Django applications`_ for an explanation of
+how to write new tests.
+
+.. _Testing Django applications: ../testing/
+
+Running the unit tests
+----------------------
+
+To run the tests, ``cd`` to the ``tests/`` directory and type::
+
+ ./runtests.py --settings=path.to.django.settings
+
+Yes, the unit tests need a settings module, but only for database connection
+info -- the ``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD``.
+You will also need a ``ROOT_URLCONF`` setting (its value is ignored; it just
+needs to be present) and a ``SITE_ID`` setting (any integer value will do) in
+order for all the tests to pass.
+
+The unit tests will not touch your existing databases; they create a new
+database, called ``django_test_db``, which is deleted when the tests are
+finished. This means your user account needs permission to execute ``CREATE
+DATABASE``.
+
+Requesting features
+===================
+
+We're always trying to make Django better, and your feature requests are a key
+part of that. Here are some tips on how to most effectively make a request:
+
+ * Request the feature on `django-developers`_, not in the ticket tracker;
+ it'll get read more closely if it's on the mailing list.
+
+ * Describe clearly and concisely what the missing feature is and how you'd
+ like to see it implemented. Include example code (non-functional is OK)
+ if possible.
+
+ * Explain *why* you'd like the feature. In some cases this is obvious, but
+ since Django is designed to help real developers get real work done,
+ you'll need to explain it, if it isn't obvious why the feature would be
+ useful.
+
+As with most open-source projects, code talks. If you are willing to write the
+code for the feature yourself or if (even better) you've already written it,
+it's much more likely to be accepted. If it's a large feature that might need
+multiple developers we're always happy to give you an experimental branch in
+our repository; see below.
+
+Branch policy
+=============
+
+In general, most development is confined to the trunk, and the trunk
+is kept stable. People should be able to run production sites against the
+trunk at any time.
+
+Thus, large architectural changes -- that is, changes too large to be
+encapsulated in a single patch, or changes that need multiple eyes on them --
+will have dedicated branches. See, for example, the `i18n branch`_. If you
+have a change of this nature that you'd like to work on, ask on
+`django-developers`_ for a branch to be created for you. We'll create a branch
+for pretty much any kind of experimenting you'd like to do.
+
+We will only branch entire copies of the Django tree, even if work is only
+happening on part of that tree. This makes it painless to switch to a branch.
+
+Developers working on a branch should periodically merge changes from the trunk
+into the branch. Please merge at least once a week. Every time you merge from
+the trunk, note the merge and revision numbers in the commit message.
+
+Once the branch is stable and ready to be merged into the trunk, alert
+`django-developers`_.
+
+After a branch has been merged, it should be considered "dead"; write access to
+it will be disabled, and old branches will be periodically "trimmed." To keep
+our SVN wrangling to a minimum, we won't be merging from a given branch into the
+trunk more than once.
+
+Using branches
+--------------
+
+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>/
+
+...where ``<branch>`` 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/<branch>/
+
+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. 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.
+
+A third option is to use a `path file`_ (``<something>.pth``) which should
+work on all systems (including Windows, which doesn't have symlinks
+available). First, make sure there are no files, directories or symlinks named
+``django`` in your ``site-packages`` directory. Then create a text file named
+``django.pth`` and save it to your ``site-packages`` directory. That file
+should contain a path to your copy of Django on a single line and optional
+comments. Here is an example that points to multiple branches. Just uncomment
+the line for the branch you want to use ('Trunk' in this example) and make
+sure all other lines are commented::
+
+ # Trunk is a svn checkout of:
+ # http://code.djangoproject.com/svn/django/trunk/
+ #
+ /path/to/trunk
+
+ # <branch> is a svn checkout of:
+ # http://code.djangoproject.com/svn/django/branches/<branch>/
+ #
+ #/path/to/<branch>
+
+ # On windows a path may look like this:
+ # C:/path/to/<branch>
+
+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``.
+
+.. _path file: http://docs.python.org/lib/module-site.html
+
+Official releases
+=================
+
+Django's release numbering works as follows:
+
+ * Versions are numbered in the form ``A.B`` or ``A.B.C``.
+
+ * ``A`` is the major version number, which is only incremented for major
+ changes to Django, and these changes are not necessarily
+ backwards-compatible. That is, code you wrote for Django 6.0 may break
+ when we release Django 7.0.
+
+ * ``B`` is the minor version number, which is incremented for large yet
+ backwards compatible changes. Code written for Django 6.4 will continue
+ to work under Django 6.5.
+
+ A minor release may deprecate certain features in previous releases. If a
+ feature in version ``A.B`` is deprecated, it will continue to work in
+ version ``A.B+1``. In version ``A.B+2``, use of the feature will raise a
+ ``PendingDeprecationWarning`` but will continue to work. Version
+ ``A.B+3`` will remove the feature entirely. Major point releases will
+ always remove deprecated features immediately.
+
+ * ``C`` is the micro version number which, is incremented for bug and
+ security fixes. A new micro-release will always be 100%
+ backwards-compatible with the previous micro-release.
+
+ * In some cases, we'll make release candidate releases. These are of the
+ form ``A.BrcN``, which means the ``Nth`` candidate release of version
+ ``A.B``.
+
+An exception to this version numbering scheme is the pre-1.0 Django code.
+There's no guarantee of backwards-compatibility until the 1.0 release.
+
+In Subversion, each Django release will be tagged under `tags/releases`_. If
+it's necessary to release a bug fix release or a security release that doesn't
+come from the trunk, we'll copy that tag to ``branches/releases`` to make the
+bug fix release.
+
+Deciding on features
+====================
+
+Once a feature's been requested and discussed, eventually we'll have a decision
+about whether to include the feature or drop it.
+
+Whenever possible, we strive for a rough consensus. To that end, we'll often
+have informal votes on `django-developers`_ about a feature. In these votes we
+follow the voting style invented by Apache and used on Python itself, where
+votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:
+
+ * +1: "I love the idea and I'm strongly committed to it."
+
+ * +0: "Sounds OK to me."
+
+ * -0: "I'm not thrilled, but I won't stand in the way."
+
+ * -1: "I strongly disagree and would be very unhappy to see the idea turn
+ into reality."
+
+Although these votes on django-developers are informal, they'll be taken very
+seriously. After a suitable voting period, if an obvious consensus arises
+we'll follow the votes.
+
+However, consensus is not always possible. Tough decisions will be discussed by
+all full committers and finally decided by the Benevolent Dictators for Life,
+Adrian and Jacob.
+
+Commit access
+=============
+
+Django has two types of committers:
+
+Full committers
+ These are people who have a long history of contributions to Django's
+ codebase, a solid track record of being polite and helpful on the mailing
+ lists, and a proven desire to dedicate serious time to Django's development.
+
+ The bar is very high for full commit access. It will only be granted by
+ unanimous approval of all existing full committers, and the decision will err
+ on the side of rejection.
+
+Partial committers
+ These are people who are "domain experts." They have direct check-in 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.
+
+ Like full committers, partial commit access is by unanimous approval of all
+ full committers (and any other partial committers in the same area).
+ However, the bar is set lower; proven expertise in the area in question is
+ likely to be sufficient.
+
+To request commit access, please contact an existing committer privately. Public
+requests for commit access are potential flame-war starters, and will be ignored.
+
+.. _community page: http://www.djangoproject.com/community/
+.. _ticket tracker: http://code.djangoproject.com/newticket
+.. _django-developers: http://groups.google.com/group/django-developers
+.. _FAQ: http://www.djangoproject.com/documentation/faq/
+.. _search the tracker: http://code.djangoproject.com/search
+.. _django-users: http://groups.google.com/group/django-users
+.. _`#django`: irc://irc.freenode.net/django
+.. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority
+.. _PEP 8: http://www.python.org/peps/pep-0008.html
+.. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n
+.. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases