Fixed #16469 -- Improved documentation of Django internals, including the new backport policy. Many thanks to Aymeric Augustin.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16548 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jannis Leidel
parent
8f7b5024b2
commit
127b7fdce8
|
|
@ -2,14 +2,14 @@
|
|||
Reporting bugs and requesting features
|
||||
======================================
|
||||
|
||||
Before reporting a bug or requesting a new feature please consider these
|
||||
Before reporting a bug or requesting a new feature, please consider these
|
||||
general points:
|
||||
|
||||
* Check that someone hasn't already filed the bug or feature request by
|
||||
`searching`_ or running `custom queries`_ in the ticket tracker.
|
||||
|
||||
* Don't use the ticket system to ask support questions. Use the
|
||||
`django-users`_ list, or the `#django`_ IRC channel for that.
|
||||
`django-users`_ list or the `#django`_ IRC channel for that.
|
||||
|
||||
* Don't reopen issues that have been marked "wontfix" by a core developer.
|
||||
This mark means that the decision has been made that we can't or won't fix
|
||||
|
|
@ -17,7 +17,7 @@ general points:
|
|||
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
|
||||
likely to get lost. If a particular ticket is controversial, please move the
|
||||
discussion to `django-developers`_.
|
||||
|
||||
.. _reporting-bugs:
|
||||
|
|
@ -33,19 +33,19 @@ particular:
|
|||
* **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
|
||||
be a well-known question.
|
||||
|
||||
* **Do** ask on `django-users`_ *first* if you're not sure if what you're
|
||||
seeing is a bug.
|
||||
* **Do** ask on `django-users`_ or `#django`_ *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.
|
||||
* **Do** write complete, reproducible, specific bug reports. You must
|
||||
include a clear, concise description of the problem, and a set of
|
||||
instructions for replicating it. Add as much debug information as you can:
|
||||
code snippets, test cases, exception backtraces, screenshots, etc. A nice
|
||||
small test case is the best way to report a bug, as it gives us an easy
|
||||
way to confirm the bug quickly.
|
||||
|
||||
* **Don't** post to django-developers just to announce that you have filed
|
||||
a bug report. All the tickets are mailed to another list
|
||||
(`django-updates`_), which is tracked by developers and interested
|
||||
* **Don't** post to `django-developers`_ just to announce that you have
|
||||
filed a bug report. All the tickets are mailed to another list,
|
||||
`django-updates`_, which is tracked by developers and interested
|
||||
community members; we see them as they are filed.
|
||||
|
||||
To understand the lifecycle of your ticket once you have created it, refer to
|
||||
|
|
@ -95,8 +95,18 @@ 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 make a request most effectively:
|
||||
|
||||
* First request the feature on `django-developers`_, not in the ticket
|
||||
tracker. It'll get read more closely if it's on the mailing list.
|
||||
* Make sure the feature actually requires changes in Django's core. If your
|
||||
idea can be developed as an independent application or module — for
|
||||
instance, you want to support another database engine — we'll probably
|
||||
suggest that you to develop it independently. Then, if your project
|
||||
gathers sufficient community support, we may consider it for inclusion in
|
||||
Django.
|
||||
|
||||
* First request the feature on the `django-developers`_ list, not in the
|
||||
ticket tracker. It'll get read more closely if it's on the mailing list.
|
||||
This is even more important for large-scale feature requests. We like to
|
||||
discuss any big changes to Django's core on the mailing list before
|
||||
actually working on them.
|
||||
|
||||
* 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)
|
||||
|
|
@ -107,19 +117,16 @@ part of that. Here are some tips on how to make a request most effectively:
|
|||
you'll need to explain it, if it isn't obvious why the feature would be
|
||||
useful.
|
||||
|
||||
* 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.
|
||||
If core developers agree on the feature, then it's appropriate to create a
|
||||
ticket. Include a link the discussion on `django-developers`_ in the ticket
|
||||
description.
|
||||
|
||||
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,
|
||||
code for the feature yourself or, even better, if 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 the :doc:`writing-code/branch-policy`.
|
||||
|
||||
To understand the lifecycle of your ticket once you have created it, refer to
|
||||
:doc:`triaging-tickets`.
|
||||
|
||||
See also: :ref:`documenting-new-features`.
|
||||
|
||||
.. _how-we-make-decisions:
|
||||
|
|
@ -141,9 +148,9 @@ votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:
|
|||
* -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.
|
||||
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. If consensus cannot be reached, or
|
||||
if the discussion towards a consensus fizzles out without a concrete decision,
|
||||
|
|
@ -175,7 +182,7 @@ committers -- may be held in private.
|
|||
|
||||
|
||||
.. _searching: http://code.djangoproject.com/search
|
||||
.. _`custom queries`: https://code.djangoproject.com/query
|
||||
.. _custom queries: https://code.djangoproject.com/query
|
||||
.. _django-developers: http://groups.google.com/group/django-developers
|
||||
.. _django-users: http://groups.google.com/group/django-users
|
||||
.. _`#django`: irc://irc.freenode.net/django
|
||||
.. _#django: irc://irc.freenode.net/django
|
||||
|
|
|
|||
|
|
@ -28,11 +28,9 @@ Partial committers
|
|||
in question is likely to be sufficient.
|
||||
|
||||
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.
|
||||
: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.
|
||||
|
||||
Committing guidelines
|
||||
---------------------
|
||||
|
|
@ -69,12 +67,12 @@ repository:
|
|||
|
||||
* Separate bug fixes from feature changes.
|
||||
|
||||
Bug fixes need to be added to the current bugfix branch (e.g. the
|
||||
``1.0.X`` branch) as well as the current trunk.
|
||||
Bug fixes need to be added to the current bugfix branch as well as the
|
||||
current trunk.
|
||||
|
||||
* 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 -- Adde
|
||||
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.
|
||||
|
|
@ -83,7 +81,7 @@ repository:
|
|||
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.
|
||||
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
|
||||
|
||||
|
|
@ -111,8 +109,8 @@ discovered, please follow these guidelines:
|
|||
|
||||
* If the original author can't be reached (within a reasonable amount
|
||||
of time -- a day or so) and the problem is severe -- crashing bug,
|
||||
major test failures, etc -- then ask for objections on django-dev
|
||||
then revert if there are none.
|
||||
major test failures, etc -- then ask for objections on the
|
||||
`django-developers`_ mailing list then revert if there are none.
|
||||
|
||||
* If the problem is small (a feature commit after feature freeze,
|
||||
say), wait it out.
|
||||
|
|
|
|||
|
|
@ -2,17 +2,34 @@
|
|||
Contributing to Django
|
||||
======================
|
||||
|
||||
Django is a community that lives on its volunteers. As it keeps growing, we
|
||||
always need more people to help others. As soon as you learn Django, you can
|
||||
contribute in many ways:
|
||||
|
||||
* Join the `django-users`_ mailing list and answer questions. This
|
||||
mailing list has a huge audience, and we really want to maintain a
|
||||
friendly and helpful atmosphere. If you're new to the Django community,
|
||||
you should read the `posting guidelines`_.
|
||||
|
||||
* Join the `#django IRC channel`_ on Freenode and answer questions. By
|
||||
explaining Django to other users, you're going to learn a lot about the
|
||||
framework yourself.
|
||||
|
||||
* Blog about Django. We syndicate all the Django blogs we know about on
|
||||
the `community page`_; if you'd like to see your blog on that page you
|
||||
can `register it here`_.
|
||||
|
||||
* Contribute to open-source Django projects, write some documentation, or
|
||||
release your own code as an open-source pluggable application. The
|
||||
ecosystem of pluggable applications is a big strength of Django, help us
|
||||
build it!
|
||||
|
||||
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 several ways you can help Django's
|
||||
development:
|
||||
|
||||
* Blog about Django. We syndicate all the Django blogs we know about on
|
||||
the `community page`_; if you'd like to see your blog on that page you
|
||||
can `register it here`_.
|
||||
|
||||
* :doc:`Report bugs and request features<bugs-and-features>` in our
|
||||
`ticket tracker`_.
|
||||
* :doc:`Report bugs <bugs-and-features>` in our `ticket tracker`_.
|
||||
|
||||
* Join the `django-developers`_ mailing list and share your ideas for how
|
||||
to improve Django. We're always open to suggestions.
|
||||
|
|
@ -24,11 +41,12 @@ development:
|
|||
* :doc:`Improve the documentation <writing-documentation>` or
|
||||
:doc:`write unit tests <writing-code/unit-tests>`.
|
||||
|
||||
* :doc:`Triage tickets<triaging-tickets>` that have been created by other
|
||||
users.
|
||||
* :doc:`Triage tickets and review patches <triaging-tickets>` created by
|
||||
other users.
|
||||
|
||||
... and many more ways! Really, **ANYONE** can do something to help make
|
||||
Django better and greater. Browse the following sections to find out how:
|
||||
Really, **ANYONE** can do something to help make Django better and greater!
|
||||
|
||||
Browse the following sections to find out how:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
|
@ -41,8 +59,11 @@ Django better and greater. Browse the following sections to find out how:
|
|||
translations
|
||||
committing-code
|
||||
|
||||
.. _django-users: http://groups.google.com/group/django-users
|
||||
.. _posting guidelines: https://code.djangoproject.com/wiki/UsingTheMailingList
|
||||
.. _#django IRC channel: irc://irc.freenode.net/django
|
||||
.. _community page: http://www.djangoproject.com/community/
|
||||
.. _register it here: http://www.djangoproject.com/community/add/blogs/
|
||||
.. _django-developers: http://groups.google.com/group/django-developers
|
||||
.. _ticket tracker: http://code.djangoproject.com/newticket
|
||||
.. _community page: http://www.djangoproject.com/community/
|
||||
.. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1
|
||||
.. _`register it here`: http://www.djangoproject.com/community/add/blogs/
|
||||
.. _easy pickings: http://code.djangoproject.com/query?status=!closed&easy=1
|
||||
|
|
|
|||
|
|
@ -5,15 +5,14 @@ Advice for new contributors
|
|||
New contributor and not sure what to do? Want to help but just don't know how
|
||||
to get started? This is the section for you.
|
||||
|
||||
* **Pick a subject area that you care about, that you are familiar with, or
|
||||
that you want to learn about**
|
||||
First steps
|
||||
-----------
|
||||
|
||||
You don't already have to be an expert on the area you want to work on; you
|
||||
become an expert through your ongoing contributions to the code.
|
||||
Start with these easy tasks to discover Django's development process.
|
||||
|
||||
* **Triage tickets**
|
||||
|
||||
If a ticket is unreviewed and reports a bug, try and reproduce it. If you
|
||||
If an `unreviewed ticket`_ reports a bug, try and reproduce it. If you
|
||||
can reproduce it and it seems valid, make a note that you confirmed the bug
|
||||
and accept the ticket. Make sure the ticket is filed under the correct
|
||||
component area. Consider writing a patch that adds a test for the bug's
|
||||
|
|
@ -44,7 +43,30 @@ to get started? This is the section for you.
|
|||
:doc:`writing-documentation`, in particular the tips for
|
||||
:ref:`improving-the-documentation`.
|
||||
|
||||
* **Analyze the ticket's context and history**
|
||||
.. note::
|
||||
|
||||
The `reports page`_ contains links to many useful Trac queries, including
|
||||
several that are useful for triaging tickets and reviewing patches as
|
||||
suggested above.
|
||||
|
||||
.. _reports page: http://code.djangoproject.com/wiki/Reports
|
||||
|
||||
.. _unreviewed ticket: http://code.djangoproject.com/query?status=!closed&stage=Unreviewed
|
||||
|
||||
|
||||
Guidelines
|
||||
----------
|
||||
|
||||
As a newcomer on a large project, it's easy to experience frustration. Here's
|
||||
some advice to make your work on Django more useful and rewarding.
|
||||
|
||||
* **Pick a subject area that you care about, that you are familiar with, or
|
||||
that you want to learn about**
|
||||
|
||||
You don't already have to be an expert on the area you want to work on; you
|
||||
become an expert through your ongoing contributions to the code.
|
||||
|
||||
* **Analyze tickets' context and history**
|
||||
|
||||
Trac isn't an absolute; the context is just as important as the words.
|
||||
When reading Trac, you need to take into account who says things, and when
|
||||
|
|
@ -96,13 +118,7 @@ to get started? This is the section for you.
|
|||
writing the very first tests for that feature, not that you get a pass from
|
||||
writing tests altogether.
|
||||
|
||||
.. note::
|
||||
|
||||
The `Reports page`_ contains links to many useful Trac queries, including
|
||||
several that are useful for triaging tickets and reviewing patches as
|
||||
suggested above.
|
||||
|
||||
.. _Reports page: http://code.djangoproject.com/wiki/Reports
|
||||
.. _easy pickings: http://code.djangoproject.com/query?status=!closed&easy=1
|
||||
|
||||
.. _new-contributors-faq:
|
||||
|
||||
|
|
@ -114,7 +130,7 @@ FAQ
|
|||
|
||||
First off, it's not personal. Django is entirely developed by volunteers
|
||||
(even the core developers), and sometimes folks just don't have time. The
|
||||
best thing to do is to send a gentle reminder to the Django Developers
|
||||
best thing to do is to send a gentle reminder to the django-developers
|
||||
mailing list asking for review on the ticket, or to bring it up in the
|
||||
#django-dev IRC channel.
|
||||
|
||||
|
|
@ -130,8 +146,6 @@ FAQ
|
|||
Design Decision Needed requires consensus about the right solution. At the
|
||||
very least it needs consensus among the core developers, and ideally it has
|
||||
consensus from the community as well. The best way to accomplish this is to
|
||||
start a thread on the Django Developers mailing list, and for very complex
|
||||
start a thread on the django-developers mailing list, and for very complex
|
||||
issues to start a wiki page summarizing the problem and the possible
|
||||
solutions.
|
||||
|
||||
.. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1
|
||||
|
|
|
|||
|
|
@ -3,16 +3,21 @@ Submitting and maintaining translations
|
|||
=======================================
|
||||
|
||||
Various parts of Django, such as the admin site and validation error messages,
|
||||
are internationalized. This means they display different text depending on a
|
||||
user's language setting. For this, Django uses the same internationalization
|
||||
infrastructure available to Django applications described in the
|
||||
are internationalized. This means they display different text depending on each
|
||||
user's language setting. For this, Django uses the same internationalization and
|
||||
localization infrastructure available to Django applications, described in the
|
||||
:doc:`i18n documentation</topics/i18n/index>`.
|
||||
|
||||
These translations are contributed by Django users worldwide. If you find an
|
||||
incorrect translation or want to discuss specific translations, go to the
|
||||
`translation team`_ page for that language. If you would like to help out
|
||||
with translating or add a language that isn't yet translated, here's what
|
||||
to do:
|
||||
Internationalization
|
||||
--------------------
|
||||
|
||||
Translations are contributed by Django users worldwide. The translation work is
|
||||
coordinated at `Transifex`_.
|
||||
|
||||
If you find an incorrect translation or want to discuss specific translations,
|
||||
go to the `translation team`_ page for that language. If you would like to help
|
||||
out with translating or add a language that isn't yet translated, here's what to
|
||||
do:
|
||||
|
||||
* Join the `Django i18n mailing list`_ and introduce yourself.
|
||||
|
||||
|
|
@ -20,7 +25,7 @@ to do:
|
|||
|
||||
* Signup at `Transifex`_ and visit the `Django project page`_.
|
||||
|
||||
* On the "`Translation Teams`_" page, choose the language team you want
|
||||
* On the `translation teams`_ page, choose the language team you want
|
||||
to work with, **or** -- in case the language team doesn't exist yet --
|
||||
request a new team by clicking on the "Request a new team" button
|
||||
and select the appropriate language.
|
||||
|
|
@ -37,24 +42,27 @@ to do:
|
|||
Each of the contrib apps also have a resource (prefixed with "contrib").
|
||||
|
||||
.. note::
|
||||
For more information about how to use Transifex, see the
|
||||
`Transifex Help`_
|
||||
For more information about how to use Transifex, read the
|
||||
`Transifex User Guide`_.
|
||||
|
||||
* Optionally, review and update the ``conf/locale/<locale>/formats.py``
|
||||
file to describe the date, time and numbers formatting particularities
|
||||
of your locale. These files aren't covered by the use of Transifex and
|
||||
require a patch against the Django source tree, just as a code change
|
||||
would:
|
||||
Localization
|
||||
------------
|
||||
|
||||
You can also review ``conf/locale/<locale>/formats.py``. This file describes
|
||||
the date, time and numbers formatting particularities of your locale. See
|
||||
:ref:`format-localization` for details.
|
||||
|
||||
The format files aren't managed by the use of Transifex. To change them, you
|
||||
must :doc:`create a patch<writing-code/submitting-patches>` against the Django source tree, as for any code change:
|
||||
|
||||
* Create a diff against the current Subversion trunk.
|
||||
|
||||
* Open a ticket in Django's ticket system, set its ``Component`` field
|
||||
to ``Translations``, and attach the patch to it. See
|
||||
:ref:`format-localization` for details.
|
||||
* Open a ticket in Django's ticket system, set its ``Component`` field to
|
||||
``Translations``, and attach the patch to it.
|
||||
|
||||
.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
|
||||
.. _Transifex: http://www.transifex.net/
|
||||
.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
|
||||
.. _Django project page: http://www.transifex.net/projects/p/django/
|
||||
.. _translation teams: http://www.transifex.net/projects/p/django/teams/
|
||||
.. _translation team: http://www.transifex.net/projects/p/django/teams/
|
||||
.. _Transifex Help: http://help.transifex.net/
|
||||
.. _translation teams: http://www.transifex.net/projects/p/django/teams/
|
||||
.. _Transifex User Guide: http://help.transifex.net/
|
||||
|
|
|
|||
|
|
@ -2,11 +2,12 @@
|
|||
Triaging tickets
|
||||
================
|
||||
|
||||
Django uses Trac_ for managing our progress, and Trac is a community-tended
|
||||
garden of the bugs people have found and the features people would like to see
|
||||
added. As in any garden, sometimes there are weeds to be pulled and sometimes
|
||||
there are flowers and vegetables that need picking. We need your help to sort
|
||||
out one from the other, and in the end we all benefit together.
|
||||
Django uses Trac_ for managing the work on the code base. Trac is a
|
||||
community-tended garden of the bugs people have found and the features people
|
||||
would like to see added. As in any garden, sometimes there are weeds to be
|
||||
pulled and sometimes there are flowers and vegetables that need picking. We need
|
||||
your help to sort out one from the other, and in the end we all benefit
|
||||
together.
|
||||
|
||||
Like all gardens, we can aspire to perfection but in reality there's no such
|
||||
thing. Even in the most pristine garden there are still snails and insects.
|
||||
|
|
@ -39,8 +40,8 @@ tickets have patches, but those patches don't meet all the requirements of a
|
|||
:ref:`good patch<patch-style>`.
|
||||
|
||||
One way to help out is to *triage* tickets that have been created by other
|
||||
users. The core team--as well as many community members--work on this
|
||||
regularly, but more help is always appreciated.
|
||||
users. The core team and several community members work on this regularly, but
|
||||
more help is always appreciated.
|
||||
|
||||
Most of the workflow is based around the concept of a ticket's
|
||||
:ref:`triage stages <triage-stages>`. Each stage describes where in its
|
||||
|
|
@ -146,11 +147,10 @@ made by the core committers, however that is not a requirement. See the
|
|||
:ref:`New contributors' FAQ<new-contributors-faq>` for "My ticket has been in
|
||||
DDN forever! What should I do?"
|
||||
|
||||
This stage will generally only be used for feature
|
||||
requests. It can also be used for issues that *might* be bugs, depending on
|
||||
opinion or interpretation. Obvious bugs (such as crashes, incorrect query
|
||||
results, or non-compliance with a standard) skip this stage and move straight
|
||||
to "Accepted".
|
||||
This stage will often be used for feature requests. It can also be used for
|
||||
issues that *might* be bugs, depending on opinion or interpretation. Obvious
|
||||
bugs (such as crashes, incorrect query results, or non-compliance with a
|
||||
standard) skip this stage and move straight to "Accepted".
|
||||
|
||||
Ready For Checkin
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -200,7 +200,7 @@ A number of flags, appearing as checkboxes in Trac, can be set on a ticket:
|
|||
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, there is a flaw in the implementation, or that the code
|
||||
doesn't meet our standards."
|
||||
doesn't meet our standards.
|
||||
* Easy pickings
|
||||
Tickets that would require small, easy, patches.
|
||||
|
||||
|
|
@ -250,7 +250,7 @@ If you do close a ticket, you should always make sure of the following:
|
|||
* If there is a way they can improve the ticket to reopen it, let them know.
|
||||
|
||||
* If the ticket is a duplicate, reference the original ticket. Also
|
||||
cross-reference the closed ticket by living a comment in the original one
|
||||
cross-reference the closed ticket by leaving a comment in the original one
|
||||
-- this allows to access more related information about the reported bug
|
||||
or requested feature.
|
||||
|
||||
|
|
@ -279,7 +279,7 @@ A ticket can be resolved in a number of ways:
|
|||
discussion in the `django-developers`_ mailing list. Feel free to
|
||||
start or join in discussions of "wontfix" tickets on the
|
||||
django-developers_ mailing list, but please do not reopen tickets
|
||||
closed as "wontfix" by core developers.
|
||||
closed as "wontfix" by a :doc:`core developer</internals/committers>`.
|
||||
|
||||
* duplicate
|
||||
Used when another ticket covers the same issue. By closing duplicate
|
||||
|
|
@ -371,9 +371,9 @@ the ticket database:
|
|||
checkin", but you should get at minimum one other community member to
|
||||
review a patch that you submit.
|
||||
|
||||
* Please **don't** reverse a decision that has been made by a core
|
||||
developer. If you disagree with a decision that has been made,
|
||||
please post a message to `django-developers`_.
|
||||
* Please **don't** reverse a decision that has been made by a :doc:`core
|
||||
developer</internals/committers>`. If you disagree with a decision that
|
||||
has been made, please post a message to `django-developers`_.
|
||||
|
||||
* If you're unsure if you should be making a change, don't make the
|
||||
change but instead leave a comment with your concerns on the ticket,
|
||||
|
|
|
|||
|
|
@ -146,15 +146,14 @@ 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::
|
||||
A third option is to use a `path file`_ (``<something>.pth``). 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/
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ Python style
|
|||
|
||||
* Unless otherwise specified, follow :pep:`8`.
|
||||
|
||||
You could use a tool like `pep8.py`_ to check for some problems in this
|
||||
You could use a tool like `pep8`_ to check for some problems in this
|
||||
area, but remember that PEP 8 is only a guide, so respect the style of
|
||||
the surrounding code as a primary goal.
|
||||
|
||||
|
|
@ -171,9 +171,9 @@ That means that the ability for third parties to import the module at the top
|
|||
level is incompatible with the ability to configure the settings object
|
||||
manually, or makes it very difficult in some circumstances.
|
||||
|
||||
Instead of the above code, a level of laziness or indirection must be used,
|
||||
such as `django.utils.functional.LazyObject``, ``django.utils.functional.lazy``
|
||||
or ``lambda``.
|
||||
Instead of the above code, a level of laziness or indirection must be used, such
|
||||
as :class:`django.utils.functional.LazyObject`,
|
||||
:func:`django.utils.functional.lazy` or ``lambda``.
|
||||
|
||||
Miscellaneous
|
||||
-------------
|
||||
|
|
@ -181,10 +181,15 @@ Miscellaneous
|
|||
* Mark all strings for internationalization; see the :doc:`i18n
|
||||
documentation </topics/i18n/index>` for details.
|
||||
|
||||
* Remove ``import`` statements that are no longer used when you change code.
|
||||
The most common tools for this task are `pyflakes`_ and `pylint`_.
|
||||
|
||||
* 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.
|
||||
|
||||
.. _pep8.py: http://pypi.python.org/pypi/pep8/
|
||||
.. _pep8: http://pypi.python.org/pypi/pep8
|
||||
.. _pyflakes: http://pypi.python.org/pypi/pyflakes
|
||||
.. _pylint: http://pypi.python.org/pypi/pylint
|
||||
|
|
|
|||
|
|
@ -84,7 +84,7 @@ Patch style
|
|||
Patches in ``git diff`` format are also acceptable.
|
||||
|
||||
* When creating patches, always run ``svn diff`` from the top-level
|
||||
``trunk`` directory -- i.e., the one that contains ``django``, ``docs``,
|
||||
``trunk`` directory -- i.e. the one that contains ``django``, ``docs``,
|
||||
``tests``, ``AUTHORS``, etc. This makes it easy for other people to
|
||||
apply your patches.
|
||||
|
||||
|
|
@ -101,8 +101,8 @@ Patch style
|
|||
|
||||
* 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).
|
||||
include a regression test to validate the behavior that has been fixed,
|
||||
to 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
|
||||
|
|
@ -130,13 +130,13 @@ Serving compressed or "minified" versions of javascript files is considered
|
|||
best practice in this regard.
|
||||
|
||||
To that end, patches for javascript files should include both the original
|
||||
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
|
||||
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.
|
||||
|
||||
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 ``/contrib/admin/media/js/compress.py``.
|
||||
This script is located at ``django/contrib/admin/static/js/compress.py``.
|
||||
|
||||
Behind the scenes, ``compress.py`` is a front-end for Google's
|
||||
`Closure Compiler`_ which is written in Java. However, the Closure Compiler
|
||||
|
|
@ -148,7 +148,7 @@ 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
|
||||
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
|
||||
the default ``/usr/bin/java`` command may remain linked to the previous Java
|
||||
binary, so relinking that command may be necessary as well.
|
||||
|
||||
Please don't forget to run ``compress.py`` and include the ``diff`` of the
|
||||
|
|
|
|||
|
|
@ -3,13 +3,13 @@ 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.
|
||||
code base. It's our policy to make sure all tests pass at all times.
|
||||
|
||||
The tests cover:
|
||||
|
||||
* Models and the database API (``tests/modeltests/``).
|
||||
* Everything else in core Django code (``tests/regressiontests``)
|
||||
* Contrib apps (``django/contrib/<contribapp>/tests``, see below)
|
||||
* Models and the database API (``tests/modeltests``),
|
||||
* Everything else in core Django code (``tests/regressiontests``),
|
||||
* :ref:`contrib-apps` (``django/contrib/<app>/tests``).
|
||||
|
||||
We appreciate any and all contributions to the test suite!
|
||||
|
||||
|
|
@ -105,8 +105,8 @@ internationalization, type:
|
|||
./runtests.py --settings=path.to.settings generic_relations i18n
|
||||
|
||||
How do you find out the names of individual tests? Look in
|
||||
``tests/modeltests`` and ``tests/regressiontests`` -- each directory name
|
||||
there is the name of a test.
|
||||
``tests/modeltests`` and ``tests/regressiontests`` — each directory name
|
||||
there is the name of a test. Contrib app names are also valid test names.
|
||||
|
||||
If you just want to run a particular class of tests, you can specify a list of
|
||||
paths to individual test classes. For example, to run the ``TranslationTests``
|
||||
|
|
@ -150,16 +150,17 @@ associated tests will be skipped.
|
|||
.. _memcached: http://www.danga.com/memcached/
|
||||
.. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
|
||||
|
||||
.. _contrib-apps:
|
||||
|
||||
Contrib apps
|
||||
------------
|
||||
|
||||
Tests for apps in ``django/contrib/`` go in their respective directories under
|
||||
``django/contrib/``, in a ``tests.py`` file. (You can split the tests over
|
||||
multiple modules by using a ``tests`` directory in the normal Python way.)
|
||||
Tests for contrib apps go in their respective directories under
|
||||
``django/contrib``, in a ``tests.py`` file. You can split the tests over
|
||||
multiple modules by using a ``tests`` directory in the normal Python way.
|
||||
|
||||
For the tests to be found, a ``models.py`` file must exist (it doesn't
|
||||
have to have anything in it). If you have URLs that need to be
|
||||
mapped, put them in ``tests/urls.py``.
|
||||
For the tests to be found, a ``models.py`` file must exist, even if it's empty.
|
||||
If you have URLs that need to be mapped, put them in ``tests/urls.py``.
|
||||
|
||||
To run tests for just one contrib app (e.g. ``markup``), use the same
|
||||
method as above::
|
||||
|
|
|
|||
|
|
@ -9,10 +9,10 @@ possible.
|
|||
|
||||
Documentation changes generally come in two forms:
|
||||
|
||||
* General improvements -- Typo corrections, error fixes and better
|
||||
* General improvements: typo corrections, error fixes and better
|
||||
explanations through clearer writing and more examples.
|
||||
|
||||
* New features -- Documentation of features that have been added to the
|
||||
* New features: documentation of features that have been added to the
|
||||
framework since the last release.
|
||||
|
||||
This section explains how writers can craft their documentation changes
|
||||
|
|
@ -61,17 +61,13 @@ documentation:
|
|||
|
||||
* **email** -- no hyphen.
|
||||
|
||||
* **MySQL**
|
||||
|
||||
* **PostgreSQL**
|
||||
* **MySQL**, **PostgreSQL**, **SQLite**
|
||||
|
||||
* **Python** -- when referring to the language, capitalize Python.
|
||||
|
||||
* **realize**, **customize**, **initialize**, etc. -- use the American
|
||||
"ize" suffix, not "ise."
|
||||
|
||||
* **SQLite**
|
||||
|
||||
* **subclass** -- it's a single word without a hyphen, both as a verb
|
||||
("subclass that model") and as a noun ("create a subclass").
|
||||
|
||||
|
|
@ -168,10 +164,10 @@ Documenting new features
|
|||
|
||||
Our policy for new features is:
|
||||
|
||||
**All documentation of new features should be written in a way that
|
||||
All documentation of new features should be written in a way that
|
||||
clearly designates the features are only available in the Django
|
||||
development version. Assume documentation readers are using the latest
|
||||
release, not the development version.**
|
||||
release, not the development version.
|
||||
|
||||
Our preferred way for marking new features is by prefacing the features'
|
||||
documentation with: "``.. versionadded:: X.Y``", followed by an optional one
|
||||
|
|
|
|||
|
|
@ -3,10 +3,12 @@ Django Deprecation Timeline
|
|||
===========================
|
||||
|
||||
This document outlines when various pieces of Django will be removed, following
|
||||
their deprecation, as per the :ref:`Django deprecation policy
|
||||
<internal-release-deprecation-policy>`
|
||||
their deprecation, as per the :ref:`deprecation policy
|
||||
<internal-release-deprecation-policy>`.
|
||||
|
||||
1.3
|
||||
---
|
||||
|
||||
* 1.3
|
||||
* ``AdminSite.root()``. This release will remove the old method for
|
||||
hooking up admin URLs. This has been deprecated since the 1.1
|
||||
release.
|
||||
|
|
@ -18,7 +20,9 @@ their deprecation, as per the :ref:`Django deprecation policy
|
|||
* The :mod:`django.contrib.gis.db.backend` module, including the
|
||||
``SpatialBackend`` interface, is deprecated since the 1.2 release.
|
||||
|
||||
* 1.4
|
||||
1.4
|
||||
---
|
||||
|
||||
* ``CsrfResponseMiddleware``. This has been deprecated since the 1.2
|
||||
release, in favor of the template tag method for inserting the CSRF
|
||||
token. ``CsrfMiddleware``, which combines ``CsrfResponseMiddleware``
|
||||
|
|
@ -111,7 +115,9 @@ their deprecation, as per the :ref:`Django deprecation policy
|
|||
beyond that of a simple ``TextField`` since the removal of oldforms.
|
||||
All uses of ``XMLField`` can be replaced with ``TextField``.
|
||||
|
||||
* 1.5
|
||||
1.5
|
||||
---
|
||||
|
||||
* The ``mod_python`` request handler has been deprecated since the 1.3
|
||||
release. The ``mod_wsgi`` handler should be used instead.
|
||||
|
||||
|
|
@ -174,7 +180,9 @@ their deprecation, as per the :ref:`Django deprecation policy
|
|||
required to end with a trailing slash to ensure there is a consistent
|
||||
way to combine paths in templates.
|
||||
|
||||
* 1.6
|
||||
1.6
|
||||
---
|
||||
|
||||
* The compatibility modules ``django.utils.copycompat`` and
|
||||
``django.utils.hashcompat`` as well as the functions
|
||||
``django.utils.itercompat.all`` and ``django.utils.itercompat.any``
|
||||
|
|
@ -226,7 +234,9 @@ their deprecation, as per the :ref:`Django deprecation policy
|
|||
were deprecated since Django 1.4 and will be removed in favor
|
||||
of the ``django.utils.text.Truncator`` class.
|
||||
|
||||
* 2.0
|
||||
2.0
|
||||
---
|
||||
|
||||
* ``django.views.defaults.shortcut()``. This function has been moved
|
||||
to ``django.contrib.contenttypes.views.shortcut()`` as part of the
|
||||
goal of removing all ``django.contrib`` references from the core
|
||||
|
|
|
|||
|
|
@ -7,30 +7,30 @@ Django's release process
|
|||
Official releases
|
||||
=================
|
||||
|
||||
Django's release numbering works as follows:
|
||||
Since version 1.0, 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.
|
||||
backwards-compatible. That is, code you wrote for Django 1.2 may break
|
||||
when we release Django 2.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.
|
||||
backwards compatible changes. Code written for Django 1.2 will continue
|
||||
to work under Django 1.3. Exceptions to this rule will be listed in the
|
||||
release notes.
|
||||
|
||||
* ``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.
|
||||
* ``C`` is the *micro version* number, which is incremented for bug and
|
||||
security fixes. A new micro-release will be 100% backwards-compatible with
|
||||
the previous micro-release. The only exception is when a security issue
|
||||
can't be fixed without breaking backwards-compatibility. If this happens,
|
||||
the release notes will provide detailed upgrade instructions.
|
||||
|
||||
* In some cases, we'll make alpha, beta, or release candidate releases.
|
||||
These are of the form ``A.B alpha/beta/rc N``, which means the ``Nth``
|
||||
alpha/beta/release candidate 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
|
||||
|
|
@ -75,9 +75,9 @@ Micro releases
|
|||
Micro releases (1.0.1, 1.0.2, 1.1.1, etc.) will be issued at least once half-way
|
||||
between minor releases, and probably more often as needed.
|
||||
|
||||
These releases will always be 100% compatible with the associated minor release
|
||||
-- the answer to "should I upgrade to the latest micro release?" will always be
|
||||
"yes."
|
||||
These releases will be 100% compatible with the associated minor release, unless
|
||||
this is impossible for security reasons. So the answer to "should I upgrade to
|
||||
the latest micro release?" will always be "yes."
|
||||
|
||||
Each minor release of Django will have a "release maintainer" appointed. This
|
||||
person will be responsible for making sure that bug fixes are applied to both
|
||||
|
|
@ -93,8 +93,20 @@ varying levels:
|
|||
* The current development trunk will get new features and bug fixes
|
||||
requiring major refactoring.
|
||||
|
||||
* All bug fixes applied to the trunk will also be applied to the last
|
||||
minor release, to be released as the next micro release.
|
||||
* Patches applied to the trunk will also be applied to the last minor
|
||||
release, to be released as the next micro release, when they fix critical
|
||||
problems:
|
||||
|
||||
* Security issues.
|
||||
|
||||
* Data-loss bugs.
|
||||
|
||||
* Crashing bugs.
|
||||
|
||||
* Major functionality bugs in newly-introduced features.
|
||||
|
||||
The rule of thumb is that fixes will be backported to the last minor
|
||||
release for bugs that would have prevented a release in the first place.
|
||||
|
||||
* Security fixes will be applied to the current trunk and the previous two
|
||||
minor releases.
|
||||
|
|
@ -104,12 +116,12 @@ Django 1.3 and 1.4. At this point in time:
|
|||
|
||||
* Features will be added to development trunk, to be released as Django 1.4.
|
||||
|
||||
* Bug fixes will be applied to a ``1.3.X`` branch, and released as 1.3.1,
|
||||
1.3.2, etc.
|
||||
* Critical bug fixes will be applied to a ``1.3.X`` branch, and released as
|
||||
1.3.1, 1.3.2, etc.
|
||||
|
||||
* Security releases will be applied to trunk, a ``1.3.X`` branch and a
|
||||
``1.2.X`` branch. Security fixes will trigger the release of ``1.3.1``,
|
||||
``1.2.1``, etc.
|
||||
* Security fixes will be applied to trunk, a ``1.3.X`` branch and a
|
||||
``1.2.X`` branch. They will trigger the release of ``1.3.1``, ``1.2.1``,
|
||||
etc.
|
||||
|
||||
.. _release-process:
|
||||
|
||||
|
|
@ -119,11 +131,11 @@ Release process
|
|||
Django uses a time-based release schedule, with minor (i.e. 1.1, 1.2, etc.)
|
||||
releases every nine months, or more, depending on features.
|
||||
|
||||
After each previous release (and after a suitable cooling-off period of a week
|
||||
or two), the core development team will examine the landscape and announce a
|
||||
timeline for the next release. Most releases will be scheduled in the 6-9 month
|
||||
range, but if we have bigger features to development we might schedule a longer
|
||||
period to allow for more ambitious work.
|
||||
After each release, and after a suitable cooling-off period of a few weeks, the
|
||||
core development team will examine the landscape and announce a timeline for the
|
||||
next release. Most releases will be scheduled in the 6-9 month range, but if we
|
||||
have bigger features to development we might schedule a longer period to allow
|
||||
for more ambitious work.
|
||||
|
||||
Release cycle
|
||||
-------------
|
||||
|
|
@ -174,10 +186,11 @@ and an rc complete with string freeze two weeks before the end of the schedule.
|
|||
Bug-fix releases
|
||||
----------------
|
||||
|
||||
After a minor release (i.e 1.1), the previous release will go into bug-fix mode.
|
||||
After a minor release (e.g. 1.1), the previous release will go into bug-fix
|
||||
mode.
|
||||
|
||||
A branch will be created of the form ``branches/releases/1.0.X`` to track
|
||||
bug-fixes to the previous release. When possible, bugs fixed on trunk must
|
||||
bug-fixes to the previous release. Critical bugs fixed on trunk must
|
||||
*also* be fixed on the bug-fix branch; this means that commits need to cleanly
|
||||
separate bug fixes from feature additions. The developer who commits a fix to
|
||||
trunk will be responsible for also applying the fix to the current bug-fix
|
||||
|
|
@ -194,9 +207,9 @@ development will be happening in a bunch of places:
|
|||
* On trunk, development towards 1.2 proceeds with small additions, bugs
|
||||
fixes, etc. being checked in daily.
|
||||
|
||||
* On the branch "branches/releases/1.1.X", bug fixes found in the 1.1
|
||||
release are checked in as needed. At some point, this branch will be
|
||||
released as "1.1.1", "1.1.2", etc.
|
||||
* On the branch "branches/releases/1.1.X", fixes for critical bugs found in
|
||||
the 1.1 release are checked in as needed. At some point, this branch will
|
||||
be released as "1.1.1", "1.1.2", etc.
|
||||
|
||||
* On the branch "branches/releases/1.0.X", security fixes are made if
|
||||
needed and released as "1.0.2", "1.0.3", etc.
|
||||
|
|
|
|||
Loading…
Reference in New Issue