Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Various documentation edits

git-svn-id: http://code.djangoproject.com/svn/django/trunk@7745 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 31ee551057598ec1c23610756750ad3b1fff94fe 1 parent 5dabaf3
Adrian Holovaty adrianholovaty authored
Showing with 45 additions and 46 deletions.
  1. +39 −40 docs/contributing.txt
  2. +4 −4 docs/db-api.txt
  3. +2 −2 docs/model-api.txt
79 docs/contributing.txt
View
@@ -238,14 +238,14 @@ Since a picture is worth a thousand words, let's start there:
We've got two official roles here:
- * Core developers: people with commit access who make the big decisions
+ * Core developers: people with commit access who make the big decisions
and write the bulk of the code.
* Ticket triagers: trusted community members with a proven history of
working with the Django community. As a result of this history, they
have been entrusted by the core developers to make some of the smaller
decisions about tickets.
-
+
Second, note the five triage stages:
1. A ticket starts as "Unreviewed", meaning that nobody has examined
@@ -254,7 +254,7 @@ Second, note the five triage stages:
2. "Design decision needed" means "this concept requires a design
decision," which should be discussed either in the ticket comments or on
`django-developers`_. The "Design decision needed" step will generally
- only be used for feature requests. It can also be used for issues
+ 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 step and move straight to "Accepted".
@@ -317,7 +317,7 @@ A ticket can be resolved in a number of ways:
tickets, we keep all the discussion in one place, which helps everyone.
"worksforme"
- Used when the the ticket doesn't contain enough detail to replicate
+ Used when the the ticket doesn't contain enough detail to replicate
the original bug.
If you believe that the ticket was closed in error -- because you're
@@ -332,50 +332,49 @@ reopen tickets that have been marked as "wontfix" by core developers.
Triage by the general community
-------------------------------
-Although the Core Developers and Ticket Triagers make the big decisions in
-the ticket triage process, there is also a lot that general community
+Although the core developers and ticket triagers make the big decisions in
+the ticket triage process, there's also a lot that general community
members can do to help the triage process. In particular, you can help out by:
- * Closing "Unreviewed" tickets as "invalid", "worksforme", or "duplicate".
+ * Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."
- * Promoting "Unreviewed" tickets to "Design Decision Required" if there
- is a design decision that needs to be made, or "Accepted" if they are
- an obvious bug.
+ * Promoting "Unreviewed" tickets to "Design decision needed" if a design
+ decision needs to be made, or "Accepted" in case of obvious bugs.
- * Correcting the "Needs Tests", "Needs documentation", or "Has Patch" flags
+ * Correcting the "Needs tests", "Needs documentation", or "Has patch" flags
for tickets where they are incorrectly set.
-
+
* Checking that old tickets are still valid. If a ticket hasn't seen
any activity in a long time, it's possible that the problem has been
- fixed, but the ticket hasn't been closed.
+ fixed but the ticket hasn't yet been closed.
- * Contact the owners of tickets that have been claimed, but have not seen
- any recent activity. If the owner doesn't respond after a week or so,
+ * Contacting the owners of tickets that have been claimed but have not seen
+ any recent activity. If the owner doesn't respond after a week or so,
remove the owner's claim on the ticket.
* Identifying trends and themes in the tickets. If there a lot of bug reports
- about a particular part of Django, it possibly indicates that we need
- to consider refactoring that part of the code. If a trend is emerging,
- you should raise it for discussion (referencing the relevant tickets)
- on `django-developers`_.
+ about a particular part of Django, it may indicate we should consider
+ refactoring that part of the code. If a trend is emerging, you should
+ raise it for discussion (referencing the relevant tickets) on
+ `django-developers`_.
-However, we do ask that as a general community member working in the
-ticket database:
+However, we do ask the following of all general community members working in
+the ticket database:
- * Please **don't** close tickets as "wontfix". The core developers will
- make the final determination of the fate of a ticket, usually after
+ * Please **don't** close tickets as "wontfix." The core developers will
+ make the final determination of the fate of a ticket, usually after
consultation with the community.
-
+
* Please **don't** promote tickets to "Ready for checkin" unless they are
- *trivial* changes - for example, spelling mistakes or
- broken links in documentation.
+ *trivial* changes -- for example, spelling mistakes or broken links in
+ documentation.
- * Please **don't** reverse a decision that has been made by a core
- developer. If you disagree with a discussion that has been made,
+ * Please **don't** reverse a decision that has been made by a core
+ developer. If you disagree with a discussion that has been made,
please post a message to `django-developers`_.
* Please be conservative in your actions. If you're unsure if you should
- be making a change, don't make the change - leave a comment with your
+ be making a change, don't make the change -- leave a comment with your
concerns on the ticket, or post a message to `django-developers`_.
Submitting and maintaining translations
@@ -739,8 +738,8 @@ If you're using another backend:
deleted when the tests are finished. This means your user account needs
permission to execute ``CREATE DATABASE``.
-If you want to run the full suite of tests, there are a number of dependencies that
-you should install:
+If you want to run the full suite of tests, you'll need to install a number of
+dependencies:
* PyYAML_
* Markdown_
@@ -748,10 +747,10 @@ you should install:
* Docutils_
* setuptools_
-Of these dependencies, setuptools_ is the only dependency that is required - if
-setuptools_ is not installed, you will get import errors when running one of
-the template tests. The tests using the other libraries will be skipped if the
-dependency can't be found.
+Of these dependencies, setuptools_ is the only dependency that is required. If
+setuptools_ is not installed, you'll get import errors when running one of
+the template tests. The tests using the other dependencies will be skipped if the
+particular library can't be found.
.. _PyYAML: http://pyyaml.org/wiki/PyYAML
.. _Markdown: http://pypi.python.org/pypi/Markdown/1.7
@@ -773,13 +772,13 @@ for generic relations and internationalization, type::
Contrib apps
------------
-Tests for apps in ``django/contrib/`` go in their respective directories,
-in a ``tests.py`` file. (You can split the tests over multiple modules
-by using a ``tests`` folder in the normal Python way).
+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.)
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, you must add them in ``tests/urls.py``.
+have to have anything in it). 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::
8 docs/db-api.txt
View
@@ -382,7 +382,7 @@ Pickling QuerySets
If you pickle_ a ``QuerySet``, this will also force all the results to be
loaded into memory prior to pickling. This is because pickling is usually used
-as a precursor to caching and when the cached queryset is reloaded, you want
+as a precursor to caching and when the cached ``QuerySet`` is reloaded, you want
the results to already be present. This means that when you unpickle a
``QuerySet``, it contains the results at the moment it was pickled, rather
than the results that are currently in the database.
@@ -2040,7 +2040,7 @@ automatically saved to the database.
One-to-one relationships
------------------------
-One-to-one relationships are very similar to Many-to-one relationships.
+One-to-one relationships are very similar to many-to-one relationships.
If you define a OneToOneField on your model, instances of that model will have
access to the related object via a simple attribute of the model.
@@ -2053,8 +2053,8 @@ For example::
ed = EntryDetail.objects.get(id=2)
ed.entry # Returns the related Entry object.
-The difference comes in reverse queries. The related model in a One-to-one
-relationship also has access to a ``Manager`` object; however, that ``Manager``
+The difference comes in "reverse" queries. The related model in a one-to-one
+relationship also has access to a ``Manager`` object, but that ``Manager``
represents a single object, rather than a collection of objects::
e = Entry.objects.get(id=2)
4 docs/model-api.txt
View
@@ -2022,7 +2022,7 @@ the ``url`` function)::
'django.views.generic.list_detail.object_detail',
name='people_view'),
-and then using that name to perform the reverse URL resolution instead
+...and then using that name to perform the reverse URL resolution instead
of the view name::
from django.db.models import permalink
@@ -2031,7 +2031,7 @@ of the view name::
return ('people_view', [str(self.id)])
get_absolute_url = permalink(get_absolute_url)
-More details on named URL patterns can be found in `URL dispatch documentation`_.
+More details on named URL patterns are in the `URL dispatch documentation`_.
.. _URL dispatch documentation: ../url_dispatch/#naming-url-patterns
Please sign in to comment.
Something went wrong with that request. Please try again.