[1.2.X] Converted the new contributions docs to unix line endings.

Backport of r15667 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@15668 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 321 insertions, 321 deletions

diff --git a/docs/howto/contribute.txt b/docs/howto/contribute.txt
index 286c9282c7..5d17ae69aa 100644
--- a/docs/howto/contribute.txt
+++ b/docs/howto/contribute.txt
@@ -1,321 +1,321 @@
-===========================

-How to contribute to Django

-===========================

-

-Django is developed 100% by the community, and the more people that are actively

-involved in the code the better Django will be. We recognize that contributing

-to Django can be daunting at first and sometimes confusing even to

-veterans. While we have our official "Contributing to Django" documentation

-which spells out the technical details of triaging tickets and submitting

-patches, it leaves a lot of room for interpretation. This guide aims to offer

-more general advice on issues such as how to interpret the various stages and

-flags in Trac, and how new contributors can get started.

-

-.. seealso::

-

-    This guide is meant to answer the most common questions about

-    contributing to Django, however it is no substitute for the

-    :doc:`/internals/contributing` reference. Please make sure to

-    read that document to understand the specific details

-    involved in reporting issues and submitting patches.

-

-.. _the-spirit-of-contributing:

-

-"The Spirit of Contributing"

-============================

-

-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.

-

-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. In a

-community garden there are also helpful people who--with the best of

-intentions--fertilize the weeds and poison the roses. It's the job of the

-community as a whole to self-manage, keep the problems to a minimum, and educate

-those coming into the community so that they can become valuable contributing

-members.

-

-Similarly, while we aim for Trac to be a perfect representation of the state of

-Django's progress, we acknowledge that this simply will not happen. By

-distributing the load of Trac maintenance to the community, we accept that there

-will be mistakes. Trac is "mostly accurate", and we give allowances for the fact

-that sometimes it will be wrong. That's okay. We're perfectionists with

-deadlines.

-

-We rely on the community to keep participating, keep tickets as accurate as

-possible, and raise issues for discussion on our mailing lists when there is

-confusion or disagreement.

-

-Django is a community project, and every contribution helps. We can't do this

-without YOU!

-

-.. _Trac: http://code.djangoproject.com/

-

-Understanding Trac

-==================

-

-Trac is Django's sole official issue tracker. All known bugs, desired features

-and ideas for changes are logged there.

-

-However, Trac can be quite confusing even to veteran contributors.  Having to

-look at both flags and triage stages isn't immediately obvious, and the stages

-themselves can be misinterpreted.

-

-.. _triage-stages-explained:

-

-What Django's triage stages "really mean"

------------------------------------------

-

-Unreviewed

-~~~~~~~~~~

-

-The ticket has not been reviewed by anyone who felt qualified to make a judgment

-about whether the ticket contained a valid issue, a viable feature, or ought to

-be closed for any of the various reasons.

-

-Accepted

-~~~~~~~~

-

-The big grey area! The absolute meaning of "accepted" is that the issue

-described in the ticket is valid and is in some stage of being worked on. Beyond

-that there are several considerations

-

-

-* **Accepted + No Flags**

-

-  The ticket is valid, but no one has submitted a patch for it yet. Often this

-  means you could safely start writing a patch for it.

-

-* **Accepted + Has Patch**

-

-  The ticket is waiting for people to review the supplied patch. This means

-  downloading the patch and trying it out, verifying that it contains tests and

-  docs, running the test suite with the included patch, and leaving feedback on

-  the ticket.

-

-

-* **Accepted + Has Patch + (any other flag)**

-

-  This means the ticket has been reviewed, and has been found to need further

-  work. "Needs tests" and "Needs documentation" are self-explanatory. "Patch

-  needs improvement" will generally be accompanied by a comment on the ticket

-  explaining what is needed to improve the code.

-

-Design Decision Needed

-~~~~~~~~~~~~~~~~~~~~~~

-

-This stage is for issues which may be contentious, may be backwards

-incompatible, or otherwise involve high-level design decisions. These decisions

-are generally made by the core committers, however that is not a

-requirement. See the FAQ below for "My ticket has been in DDN forever!  What

-should I do?"

-

-Ready For Checkin

-~~~~~~~~~~~~~~~~~

-

-The ticket was reviewed by any member of the community other than the person who

-supplied the patch and found to meet all the requirements for a commit-ready

-patch. A core committer now needs to give the patch a final review prior to

-being committed. See the FAQ below for "My ticket has been in RFC forever!  What

-should I do?"

-

-Someday/Maybe?

-~~~~~~~~~~~~~~

-

-Generally only used for vague/high-level features or design ideas. These tickets

-are uncommon and overall less useful since they don't describe concrete

-actionable issues.

-

-Fixed on a branch

-~~~~~~~~~~~~~~~~~

-

-Used to indicate that a ticket is resolved as part of a major body of work that

-will eventually be merged to trunk.  Tickets in this stage generally don't need

-further work. This may happen in the case of major features/refactors in each

-release cycle, or as part of the annual Google Summer of Code efforts.

-

-.. _closing-tickets:

-

-Closing Tickets

----------------

-

-When a ticket has completed its useful lifecycle, it's time for it to be closed.

-Closing a ticket is a big responsibility, though. You have to be sure that

-the issue is really resolved, and you need to keep in mind that the reporter

-of the ticket may not be happy to have their ticket closed (unless it's fixed,

-of course). If you're not certain about closing a ticket, just leave a comment

-with your thoughts instead.

-

-If you do close a ticket, you should always make sure of the following:

-

-  * Be certain that the issue is resolved.

-

-  * Leave a comment explaining the decision to close the ticket.

-

-  * 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.

-

-  * **Be polite.** No one likes having their ticket closed. It can be

-    frustrating or even discouraging. The best way to avoid turning people

-    off from contributing to Django is to be polite and friendly and to offer

-    suggestions for how they could improve this ticket and other tickets in the

-    future.

-

-.. seealso::

-

-    The :ref:`contributing reference <ticket-resolutions>` contains a

-    description of each of the available resolutions in Trac.

-

-Example Trac workflow

----------------------

-

-Here we see the life-cycle of an average ticket:

-

-* Alice creates a ticket, and uploads an incomplete patch (no tests, incorrect

-  implementation).

-

-* Bob reviews the patch, marks it "Accepted", "needs tests", and "patch needs

-  improvement", and leaves a comment telling Alice how the patch could be

-  improved.

-

-* Alice updates the patch, adding tests (but not changing the

-  implementation). She removes the two flags.

-

-* Charlie reviews the patch and resets the "patch needs improvement" flag with

-  another comment about improving the implementation.

-

-* Alice updates the patch, fixing the implementation. She removes the "patch

-  needs improvement" flag.

-

-* Daisy reviews the patch, and marks it RFC.

-

-* Jacob reviews the RFC patch, applies it to his checkout, and commits it.

-

-Some tickets require much less feedback than this, but then again some tickets

-require much much more.

-

-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.**

-

-  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.

-

-* **Triage tickets.**

-

-  If a ticket is unreviewed and reports a bug, try and duplicate it.  If you can

-  duplicate 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 behavior, even

-  if you don't fix the bug itself.

-

-* **Look for tickets that are accepted and review patches to build familiarity

-  with the codebase and the process.**

-

-  Mark the appropriate flags if a patch needs docs or tests. Look through the

-  changes a patch makes, and keep an eye out for syntax that is incompatible

-  with older but still supported versions of Python. Run the tests and make sure

-  they pass on your system.  Where possible and relevant, try them out on a

-  database other than SQLite. Leave comments and feedback!

-

-* **Keep old patches up to date.**

-

-  Oftentimes the codebase will change between a patch being submitted and the

-  time it gets reviewed. Make sure it still applies cleanly and functions as

-  expected. Simply updating a patch is both useful and important!

-

-* **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

-  they were said. Support for an idea two years ago doesn't necessarily mean

-  that the idea will still have support. You also need to pay attention to who

-  *hasn't* spoken -- for example, if a core team member hasn't been recently

-  involved in a discussion, then a ticket may not have the support required to

-  get into trunk.

-

-* **Start small.**

-

-  It's easier to get feedback on a little issue than on a big one.

-

-* **If you're going to engage in a big task, make sure that your idea has

-  support first.**

-

-  This means getting someone else to confirm that a bug is real before you fix

-  the issue, and ensuring that the core team supports a proposed feature before

-  you go implementing it.

-

-* **Be bold! Leave feedback!**

-

-  Sometimes it can be scary to put your opinion out to the world and say "this

-  ticket is correct" or "this patch needs work", but it's the only way the

-  project moves forward. The contributions of the broad Django community

-  ultimately have a much greater impact than that of the core developers. We

-  can't do it without YOU!

-

-* **Err on the side of caution when marking things Ready For Check-in.**

-

-  If you're really not certain if a ticket is ready, don't mark it as

-  such. Leave a comment instead, letting others know your thoughts.  If you're

-  mostly certain, but not completely certain, you might also try asking on IRC

-  to see if someone else can confirm your suspicions.

-

-* **Wait for feedback, and respond to feedback that you receive.**

-

-  Focus on one or two tickets, see them through from start to finish, and

-  repeat. The shotgun approach of taking on lots of tickets and letting some

-  fall by the wayside ends up doing more harm than good.

-

-* **Be rigorous.**

-

-  When we say ":pep:`8`, and must have docs and tests", we mean it. If a patch

-  doesn't have docs and tests, there had better be a good reason. Arguments like

-  "I couldn't find any existing tests of this feature" don't carry much

-  weight--while it may be true, that means you have the extra-important job of

-  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

-

-

-FAQs

-====

-

-**This ticket I care about has been ignored for days/weeks/months! What can I do

-to get it committed?**

-

-* First off, it's not personal. Django is entirely developed by volunteers (even

-  the core devs), and sometimes folks just don't have time. The 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.

-

-

-**I'm sure my ticket is absolutely 100% perfect, can I mark it as RFC myself?**

-

-* Short answer: No. It's always better to get another set of eyes on a

-  ticket. If you're having trouble getting that second set of eyes, see question

-  1, above.

-

-

-**My ticket has been in DDN forever! What should I do?**

-

-* 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

-  issues to start a wiki page summarizing the problem and the possible

-  solutions.

+===========================
+How to contribute to Django
+===========================
+
+Django is developed 100% by the community, and the more people that are actively
+involved in the code the better Django will be. We recognize that contributing
+to Django can be daunting at first and sometimes confusing even to
+veterans. While we have our official "Contributing to Django" documentation
+which spells out the technical details of triaging tickets and submitting
+patches, it leaves a lot of room for interpretation. This guide aims to offer
+more general advice on issues such as how to interpret the various stages and
+flags in Trac, and how new contributors can get started.
+
+.. seealso::
+
+    This guide is meant to answer the most common questions about
+    contributing to Django, however it is no substitute for the
+    :doc:`/internals/contributing` reference. Please make sure to
+    read that document to understand the specific details
+    involved in reporting issues and submitting patches.
+
+.. _the-spirit-of-contributing:
+
+"The Spirit of Contributing"
+============================
+
+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.
+
+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. In a
+community garden there are also helpful people who--with the best of
+intentions--fertilize the weeds and poison the roses. It's the job of the
+community as a whole to self-manage, keep the problems to a minimum, and educate
+those coming into the community so that they can become valuable contributing
+members.
+
+Similarly, while we aim for Trac to be a perfect representation of the state of
+Django's progress, we acknowledge that this simply will not happen. By
+distributing the load of Trac maintenance to the community, we accept that there
+will be mistakes. Trac is "mostly accurate", and we give allowances for the fact
+that sometimes it will be wrong. That's okay. We're perfectionists with
+deadlines.
+
+We rely on the community to keep participating, keep tickets as accurate as
+possible, and raise issues for discussion on our mailing lists when there is
+confusion or disagreement.
+
+Django is a community project, and every contribution helps. We can't do this
+without YOU!
+
+.. _Trac: http://code.djangoproject.com/
+
+Understanding Trac
+==================
+
+Trac is Django's sole official issue tracker. All known bugs, desired features
+and ideas for changes are logged there.
+
+However, Trac can be quite confusing even to veteran contributors.  Having to
+look at both flags and triage stages isn't immediately obvious, and the stages
+themselves can be misinterpreted.
+
+.. _triage-stages-explained:
+
+What Django's triage stages "really mean"
+-----------------------------------------
+
+Unreviewed
+~~~~~~~~~~
+
+The ticket has not been reviewed by anyone who felt qualified to make a judgment
+about whether the ticket contained a valid issue, a viable feature, or ought to
+be closed for any of the various reasons.
+
+Accepted
+~~~~~~~~
+
+The big grey area! The absolute meaning of "accepted" is that the issue
+described in the ticket is valid and is in some stage of being worked on. Beyond
+that there are several considerations
+
+
+* **Accepted + No Flags**
+
+  The ticket is valid, but no one has submitted a patch for it yet. Often this
+  means you could safely start writing a patch for it.
+
+* **Accepted + Has Patch**
+
+  The ticket is waiting for people to review the supplied patch. This means
+  downloading the patch and trying it out, verifying that it contains tests and
+  docs, running the test suite with the included patch, and leaving feedback on
+  the ticket.
+
+
+* **Accepted + Has Patch + (any other flag)**
+
+  This means the ticket has been reviewed, and has been found to need further
+  work. "Needs tests" and "Needs documentation" are self-explanatory. "Patch
+  needs improvement" will generally be accompanied by a comment on the ticket
+  explaining what is needed to improve the code.
+
+Design Decision Needed
+~~~~~~~~~~~~~~~~~~~~~~
+
+This stage is for issues which may be contentious, may be backwards
+incompatible, or otherwise involve high-level design decisions. These decisions
+are generally made by the core committers, however that is not a
+requirement. See the FAQ below for "My ticket has been in DDN forever!  What
+should I do?"
+
+Ready For Checkin
+~~~~~~~~~~~~~~~~~
+
+The ticket was reviewed by any member of the community other than the person who
+supplied the patch and found to meet all the requirements for a commit-ready
+patch. A core committer now needs to give the patch a final review prior to
+being committed. See the FAQ below for "My ticket has been in RFC forever!  What
+should I do?"
+
+Someday/Maybe?
+~~~~~~~~~~~~~~
+
+Generally only used for vague/high-level features or design ideas. These tickets
+are uncommon and overall less useful since they don't describe concrete
+actionable issues.
+
+Fixed on a branch
+~~~~~~~~~~~~~~~~~
+
+Used to indicate that a ticket is resolved as part of a major body of work that
+will eventually be merged to trunk.  Tickets in this stage generally don't need
+further work. This may happen in the case of major features/refactors in each
+release cycle, or as part of the annual Google Summer of Code efforts.
+
+.. _closing-tickets:
+
+Closing Tickets
+---------------
+
+When a ticket has completed its useful lifecycle, it's time for it to be closed.
+Closing a ticket is a big responsibility, though. You have to be sure that
+the issue is really resolved, and you need to keep in mind that the reporter
+of the ticket may not be happy to have their ticket closed (unless it's fixed,
+of course). If you're not certain about closing a ticket, just leave a comment
+with your thoughts instead.
+
+If you do close a ticket, you should always make sure of the following:
+
+  * Be certain that the issue is resolved.
+
+  * Leave a comment explaining the decision to close the ticket.
+
+  * 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.
+
+  * **Be polite.** No one likes having their ticket closed. It can be
+    frustrating or even discouraging. The best way to avoid turning people
+    off from contributing to Django is to be polite and friendly and to offer
+    suggestions for how they could improve this ticket and other tickets in the
+    future.
+
+.. seealso::
+
+    The :ref:`contributing reference <ticket-resolutions>` contains a
+    description of each of the available resolutions in Trac.
+
+Example Trac workflow
+---------------------
+
+Here we see the life-cycle of an average ticket:
+
+* Alice creates a ticket, and uploads an incomplete patch (no tests, incorrect
+  implementation).
+
+* Bob reviews the patch, marks it "Accepted", "needs tests", and "patch needs
+  improvement", and leaves a comment telling Alice how the patch could be
+  improved.
+
+* Alice updates the patch, adding tests (but not changing the
+  implementation). She removes the two flags.
+
+* Charlie reviews the patch and resets the "patch needs improvement" flag with
+  another comment about improving the implementation.
+
+* Alice updates the patch, fixing the implementation. She removes the "patch
+  needs improvement" flag.
+
+* Daisy reviews the patch, and marks it RFC.
+
+* Jacob reviews the RFC patch, applies it to his checkout, and commits it.
+
+Some tickets require much less feedback than this, but then again some tickets
+require much much more.
+
+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.**
+
+  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.
+
+* **Triage tickets.**
+
+  If a ticket is unreviewed and reports a bug, try and duplicate it.  If you can
+  duplicate 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 behavior, even
+  if you don't fix the bug itself.
+
+* **Look for tickets that are accepted and review patches to build familiarity
+  with the codebase and the process.**
+
+  Mark the appropriate flags if a patch needs docs or tests. Look through the
+  changes a patch makes, and keep an eye out for syntax that is incompatible
+  with older but still supported versions of Python. Run the tests and make sure
+  they pass on your system.  Where possible and relevant, try them out on a
+  database other than SQLite. Leave comments and feedback!
+
+* **Keep old patches up to date.**
+
+  Oftentimes the codebase will change between a patch being submitted and the
+  time it gets reviewed. Make sure it still applies cleanly and functions as
+  expected. Simply updating a patch is both useful and important!
+
+* **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
+  they were said. Support for an idea two years ago doesn't necessarily mean
+  that the idea will still have support. You also need to pay attention to who
+  *hasn't* spoken -- for example, if a core team member hasn't been recently
+  involved in a discussion, then a ticket may not have the support required to
+  get into trunk.
+
+* **Start small.**
+
+  It's easier to get feedback on a little issue than on a big one.
+
+* **If you're going to engage in a big task, make sure that your idea has
+  support first.**
+
+  This means getting someone else to confirm that a bug is real before you fix
+  the issue, and ensuring that the core team supports a proposed feature before
+  you go implementing it.
+
+* **Be bold! Leave feedback!**
+
+  Sometimes it can be scary to put your opinion out to the world and say "this
+  ticket is correct" or "this patch needs work", but it's the only way the
+  project moves forward. The contributions of the broad Django community
+  ultimately have a much greater impact than that of the core developers. We
+  can't do it without YOU!
+
+* **Err on the side of caution when marking things Ready For Check-in.**
+
+  If you're really not certain if a ticket is ready, don't mark it as
+  such. Leave a comment instead, letting others know your thoughts.  If you're
+  mostly certain, but not completely certain, you might also try asking on IRC
+  to see if someone else can confirm your suspicions.
+
+* **Wait for feedback, and respond to feedback that you receive.**
+
+  Focus on one or two tickets, see them through from start to finish, and
+  repeat. The shotgun approach of taking on lots of tickets and letting some
+  fall by the wayside ends up doing more harm than good.
+
+* **Be rigorous.**
+
+  When we say ":pep:`8`, and must have docs and tests", we mean it. If a patch
+  doesn't have docs and tests, there had better be a good reason. Arguments like
+  "I couldn't find any existing tests of this feature" don't carry much
+  weight--while it may be true, that means you have the extra-important job of
+  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
+
+
+FAQs
+====
+
+**This ticket I care about has been ignored for days/weeks/months! What can I do
+to get it committed?**
+
+* First off, it's not personal. Django is entirely developed by volunteers (even
+  the core devs), and sometimes folks just don't have time. The 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.
+
+
+**I'm sure my ticket is absolutely 100% perfect, can I mark it as RFC myself?**
+
+* Short answer: No. It's always better to get another set of eyes on a
+  ticket. If you're having trouble getting that second set of eyes, see question
+  1, above.
+
+
+**My ticket has been in DDN forever! What should I do?**
+
+* 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
+  issues to start a wiki page summarizing the problem and the possible
+  solutions.