1
0
mirror of https://github.com/django/django.git synced 2025-06-05 11:39:13 +00:00

Fixed some tiny typos in docs/contributing.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@1482 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Adrian Holovaty 2005-11-29 00:24:34 +00:00
parent 9e3efbecf8
commit e9193a79fd

View File

@ -11,20 +11,20 @@ of the community, so there are many ways you can help Django's development:
you'd like to see on that page. you'd like to see on that page.
* Report bugs and request features in our `ticket tracker`_. Please read * Report bugs and request features in our `ticket tracker`_. Please read
`reporting bugs`, below, for the details on how we like our bug reports `Reporting bugs`_, below, for the details on how we like our bug reports
served up. served up.
* Submit patches for new and/or fixed behavior. Please read the `submitting * Submit patches for new and/or fixed behavior. Please read `Submitting
patches`_, below, for the details on how to submit a patch. patches`_, below, for details on how to submit a patch.
* Join the `django-dev`_ mailing list and share your ideas for how to improve * Join the `django-dev`_ mailing list and share your ideas for how to improve
Django. We're always open to suggestions, although we're likely to be skeptical Django. We're always open to suggestions, although we're likely to be skeptical
of large-scale suggestions without some code to back it up. of large-scale suggestions without some code to back it up.
That's all you need to know if you'd like to join the Django development That's all you need to know if you'd like to join the Django development
community. The rest of this document describes the details of how our community community. The rest of this document describes the details of how our community
works and how it handles bugs, mailing lists, and all the other minutiae of how works and how it handles bugs, mailing lists, and all the other minutiae of
Django development works. Django development.
Reporting bugs Reporting bugs
============== ==============
@ -35,32 +35,32 @@ help in keeping our ticket tracker as useful as possible is appreciated. In
particular: particular:
* **Do** read the FAQ_ to see if your issue might be a well-known question. * **Do** read the FAQ_ to see if your issue might be a well-known question.
* **Do** `search the tracker`_ to see if your issue has already been filed. * **Do** `search the tracker`_ to see if your issue has already been filed.
* **Do** ask on `django-users`_ *first* if you're not sure if what you're * **Do** ask on `django-users`_ *first* if you're not sure if what you're
seeing is a bug. seeing is a bug.
* **Do** write complete, reproducible, specific bug reports. Include as * **Do** write complete, reproducible, specific bug reports. Include as
much information as you possibly can, complete with code snippets, test much information as you possibly can, complete with code snippets, test
cases, etc. A minimal example the illustrates the bug in a nice small cases, etc. A minimal example that illustrates the bug in a nice small
test case is the best possible bug report. test case is the best possible bug report.
* **Don't** use the ticket system to ask support questions. Use the * **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** use the ticket system to make large-scale feature requests. * **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-dev`_ We like to discuss any big changes to Django's core on the `django-dev`_
list before actually working on them. list before actually working on them.
* **Don't** reopen issues that have been marked "wontfix". This mark means * **Don't** reopen issues that have been marked "wontfix". This mark means
that the decision has been made that we can't or won't fix this particular that the decision has been made that we can't or won't fix this particular
issue. If you're not sure why, please ask on `django-dev`_. issue. If you're not sure why, please ask on `django-dev`_.
* **Don't** use the ticket tracker for lengthy discussions because they're * **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
discussion to `django-dev`_. discussion to `django-dev`_.
Reporting security issues Reporting security issues
========================= =========================
@ -77,12 +77,12 @@ following actions:
* Halt all other development as long as is needed to develop a fix, including * Halt all other development as long as is needed to develop a fix, including
patches against the current and two previous releases. patches against the current and two previous releases.
* Determine a go-public date for announcing the vulnerability and the fix. * Determine a go-public date for announcing the vulnerability and the fix.
To try to mitigate a possible "arms race" between those applying the patch To try to mitigate a possible "arms race" between those applying the patch
and those trying to exploit the hole, we will not announce security and those trying to exploit the hole, we will not announce security
problems immediately. problems immediately.
* Pre-notify everyone we know to be running the affected version(s) of * Pre-notify everyone we know to be running the affected version(s) of
Django. We will send these notifications through private e-mail which will Django. We will send these notifications through private e-mail which will
include documentation of the vulnerability, links to the relevant patch(es), include documentation of the vulnerability, links to the relevant patch(es),
@ -102,20 +102,24 @@ associated patches will get fixed *far* more quickly than those without patches.
Patch style Patch style
----------- -----------
* Make sure your code matches our `coding style`. * Make sure your code matches our `coding style`_.
* Submit patches in the format returned by the ``svn diff`` command. * Submit patches in the format returned by the ``svn diff`` command.
An exception is for code changes that are described more clearly in plain An exception is for code changes that are described more clearly in plain
English than in code. Indentation is the most common example; it's hard to English than in code. Indentation is the most common example; it's hard to
read patches when the only difference in code is that it's indented. read patches when the only difference in code is that it's indented.
* Attach patches to a ticket in the `ticket tracker`_, using the "attach file" * Attach patches to a ticket in the `ticket tracker`_, using the "attach file"
button. Please *don't* put the patch in the ticket description or comment button. Please *don't* put the patch in the ticket description or comment
unless it's a single line patch. unless it's a single line patch.
* Name the patch file with a ``.diff`` extension; this will let the ticket * Name the patch file with a ``.diff`` extension; this will let the ticket
tracker apply correct syntax highlighting, which is quite helpful. tracker apply correct syntax highlighting, which is quite helpful.
* Put the prefix "[patch] " before the title of your ticket. This will make
it obvious that the ticket includes a patch, and it will add the ticket
to the `list of tickets with patches`_.
Coding style Coding style
============ ============
@ -124,34 +128,45 @@ Please follow these coding standards when writing code for inclusion in Django:
* Unless otherwise specified, follow `PEP 8`_. * Unless otherwise specified, follow `PEP 8`_.
* Use four spaces for indentation. * Use four spaces for indentation.
* Use underscores, not camelCase, for variable, function and method names * Use underscores, not camelCase, for variable, function and method names
(i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``). (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``).
* Use ``InitialCaps`` for class names (or for factory functions that * Use ``InitialCaps`` for class names (or for factory functions that
return classes). return classes).
* Mark all strings for internationalization; see the `i18n documentation`_ * Mark all strings for internationalization; see the `i18n documentation`_
for details. for details.
* In Django template code, put one (and only one) space between the curly
brackets and the tag contents.
Do this::
{{ foo }}
Don't do this::
{{foo}}
Requesting features Requesting features
=================== ===================
We're always trying to make Django better, and your feature requests make that We're always trying to make Django better, and your feature requests are a key
possible. Here are some tips on how to most effectively make a request: part of that. Here are some tips on how to most effectively make a request:
* Request the feature on `django-dev`_, not in the ticket tracker; it'll get * Request the feature on `django-dev`_, not in the ticket tracker; it'll get
read more closely if it's on the mailing list. read more closely if it's on the mailing list.
* Describe clearly and concisely what the missing feature is and how you'd * 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) like to see it implemented. Include example code (non-functional is OK)
if possible. if possible.
* Explain *why* you'd like the feature. In some cases this is obvious, but * Explain *why* you'd like the feature. In some cases this is obvious, but
since Django is designed to help real developers get real work done, since Django is designed to help real developers get real work done,
you'll need to explain it if it isn't obvious why the feature would be you'll need to explain it, if it isn't obvious why the feature would be
useful. useful.
As with most open-source projects, code talks. If you are willing to write the 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 if (even better) you've already written it,
it's much more likely to be accepted. If it's a large feature that might need it's much more likely to be accepted. If it's a large feature that might need
@ -168,7 +183,7 @@ trunk at any time.
Thus, large architectural changes -- that is, changes too large to be Thus, large architectural changes -- that is, changes too large to be
encapsulated in a single patch, or changes that need multiple eyes on them -- encapsulated in a single patch, or changes that need multiple eyes on them --
will have dedicated branches. See, for example, the `i18n branch`_. If you will have dedicated branches. See, for example, the `i18n branch`_. If you
have a change of this nature that you'd like to work on, ask on `django-dev` for have a change of this nature that you'd like to work on, ask on `django-dev`_ for
a branch to be created for you. We'll create a branch for pretty much any kind of a branch to be created for you. We'll create a branch for pretty much any kind of
experimenting you'd like to do. experimenting you'd like to do.
@ -179,8 +194,8 @@ Developers working on a branch should periodically merge changes from the trunk
into the branch. Please merge at least once a week. Every time you merge from into the branch. Please merge at least once a week. Every time you merge from
the trunk, note the merge and revision numbers in the commit message. the trunk, note the merge and revision numbers in the commit message.
Once the branch is stable and ready to be merged into the trunk, alert Once the branch is stable and ready to be merged into the trunk, alert
django-dev. `django-dev`_.
After a branch has been merged, it should be considered "dead"; write access to After a branch has been merged, it should be considered "dead"; write access to
it will be disabled, and old branches will be periodically "trimmed." To keep it will be disabled, and old branches will be periodically "trimmed." To keep
@ -196,7 +211,7 @@ use::
svn switch http://code.djangoproject.com/svn/django/branches/<branch>/ svn switch http://code.djangoproject.com/svn/django/branches/<branch>/
in the root of your Django sandbox (the directory that contains ``django``, ...in the root of your Django sandbox (the directory that contains ``django``,
``docs``, and ``tests``). ``docs``, and ``tests``).
Official releases Official releases
@ -204,8 +219,8 @@ Official releases
Django's release numbering works as follows: Django's release numbering works as follows:
* Versions are numbered in the form ``A.B`` or ``A.B.C``. * Versions are numbered in the form ``A.B`` or ``A.B.C``.
* ``A`` is the major version number, which is only incremented for major * ``A`` is the major version number, which is only incremented for major
changes to Django, and these changes are not necessarily changes to Django, and these changes are not necessarily
backwards-compatible. That is, code you wrote for Django 6.0 may break backwards-compatible. That is, code you wrote for Django 6.0 may break
@ -223,16 +238,20 @@ Django's release numbering works as follows:
``A+1`` will remove the feature entirely. ``A+1`` will remove the feature entirely.
* ``C`` is the micro version number which, is incremented for bug and * ``C`` is the micro version number which, is incremented for bug and
security fixes. A new micro-release will always be 100% security fixes. A new micro-release will always be 100%
backwards-compatible with the previous micro-release. backwards-compatible with the previous micro-release.
* In some cases we'll make release candidate releases. These are of the * In some cases, we'll make release candidate releases. These are of the
form ``A.BrcN``, which means the ``Nth`` candidate release of version form ``A.BrcN``, which means the ``Nth`` candidate release of version
``A.B``. ``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 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 it's necessary to release a bug fix release or a security release that doesn't
come from the trunk, we'll copy that tag to ``branches/releases`` to make the bug fix release. come from the trunk, we'll copy that tag to ``branches/releases`` to make the
bug fix release.
Deciding on features Deciding on features
==================== ====================
@ -246,19 +265,19 @@ voting style invented by Apache and used on Python itself, where votes are given
as +1, +0, -0, or -1. Roughly translated, these votes mean: as +1, +0, -0, or -1. Roughly translated, these votes mean:
* +1: "I love the idea and I'm strongly committed to it." * +1: "I love the idea and I'm strongly committed to it."
* +0: "Sounds OK to me." * +0: "Sounds OK to me."
* -0: "I'm not thrilled, but I won't stand in the way." * -0: "I'm not thrilled, but I won't stand in the way."
* -1: "I strongly disagree and would be very unhappy to see the idea turn * -1: "I strongly disagree and would be very unhappy to see the idea turn
into reality." into reality."
Although these votes on django-dev are informal, they'll be taken very Although these votes on django-dev are informal, they'll be taken very
seriously. After a suitable voting period, if an obvious consensus arises seriously. After a suitable voting period, if an obvious consensus arises
we'll follow the votes. we'll follow the votes.
However, consensus is not always possible. Touch decisions will be discussed by However, consensus is not always possible. Tough decisions will be discussed by
all full committers and finally decided by the Benevolent Dictators for Life, all full committers and finally decided by the Benevolent Dictators for Life,
Adrian and Jacob. Adrian and Jacob.
@ -271,11 +290,11 @@ Full committers
These are people who have a long history of contributions to Django's These are people who have a long history of contributions to Django's
codebase, a solid track record of being polite and helpful on the mailing codebase, a solid track record of being polite and helpful on the mailing
lists, and a proven desire to dedicate serious time to Django's development. lists, and a proven desire to dedicate serious time to Django's development.
The bar is very high for full commit access. It will only be granted by The bar is very high for full commit access. It will only be granted by
unanimous approval of all existing full committers, and the decision will err unanimous approval of all existing full committers, and the decision will err
on the side of rejection. on the side of rejection.
Partial committers Partial committers
These are people who are "domain experts." They have direct check-in access These are people who are "domain experts." They have direct check-in access
to the subsystems that fall under their jurisdiction, and they're given a to the subsystems that fall under their jurisdiction, and they're given a
@ -287,10 +306,10 @@ Partial committers
full committers (and any other partial committers in the same area). full committers (and any other partial committers in the same area).
However, the bar is set lower; proven expertise in the area in question is However, the bar is set lower; proven expertise in the area in question is
likely to be sufficient. likely to be sufficient.
To request commit access, please contact an existing committer privately. Public To request commit access, please contact an existing committer privately. Public
requests for commit access are potential flame-war starters, and will be ignored. requests for commit access are potential flame-war starters, and will be ignored.
.. _community page: http://www.djangoproject.com/community/ .. _community page: http://www.djangoproject.com/community/
.. _ticket tracker: http://code.djangoproject.com/newticket .. _ticket tracker: http://code.djangoproject.com/newticket
.. _django-dev: http://groups.google.com/group/django-developers .. _django-dev: http://groups.google.com/group/django-developers
@ -298,6 +317,7 @@ requests for commit access are potential flame-war starters, and will be ignored
.. _search the tracker: http://code.djangoproject.com/search .. _search the tracker: http://code.djangoproject.com/search
.. _django-users: http://groups.google.com/group/django-users .. _django-users: http://groups.google.com/group/django-users
.. _`#django`: irc://irc.freenode.net/django .. _`#django`: irc://irc.freenode.net/django
.. _list of tickets with patches: http://code.djangoproject.com/report/12
.. _PEP 8: http://www.python.org/peps/pep-0008.html .. _PEP 8: http://www.python.org/peps/pep-0008.html
.. _i18n documentation: http://www.djangoproject.com/documentation/i18n/ .. _i18n documentation: http://www.djangoproject.com/documentation/i18n/
.. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n .. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n