From 31ee551057598ec1c23610756750ad3b1fff94fe Mon Sep 17 00:00:00 2001 From: Adrian Holovaty Date: Thu, 26 Jun 2008 03:59:15 +0000 Subject: [PATCH] Various documentation edits git-svn-id: http://code.djangoproject.com/svn/django/trunk@7745 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/contributing.txt | 81 +++++++++++++++++++++---------------------- docs/db-api.txt | 8 ++--- docs/model-api.txt | 4 +-- 3 files changed, 46 insertions(+), 47 deletions(-) diff --git a/docs/contributing.txt b/docs/contributing.txt index b73e3601bc..92575dd243 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -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. - * 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** promote tickets to "Ready for checkin" unless they are + *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 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:: diff --git a/docs/db-api.txt b/docs/db-api.txt index 3202bd4f9f..f80d63797a 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -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) diff --git a/docs/model-api.txt b/docs/model-api.txt index 89f5ffb812..b70cd4bea1 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -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