mirror of
https://github.com/django/django.git
synced 2024-12-22 17:16:24 +00:00
Corrected various typos in contributing docs.
This commit is contained in:
parent
bb2c5f69f4
commit
5c93a84f44
1
AUTHORS
1
AUTHORS
@ -22,6 +22,7 @@ answer newbie questions, and generally made Django that much better:
|
|||||||
Ade Lee <alee@redhat.com>
|
Ade Lee <alee@redhat.com>
|
||||||
Adiyat Mubarak <adiyatmubarak@gmail.com>
|
Adiyat Mubarak <adiyatmubarak@gmail.com>
|
||||||
Adnan Umer <u.adnan@outlook.com>
|
Adnan Umer <u.adnan@outlook.com>
|
||||||
|
Arslan Noor <arslannoorpansota@gmail.com>
|
||||||
Adrian Holovaty <adrian@holovaty.com>
|
Adrian Holovaty <adrian@holovaty.com>
|
||||||
Adrian Torres <atorresj@redhat.com>
|
Adrian Torres <atorresj@redhat.com>
|
||||||
Adrien Lemaire <lemaire.adrien@gmail.com>
|
Adrien Lemaire <lemaire.adrien@gmail.com>
|
||||||
|
@ -64,14 +64,14 @@ If your bug or feature request touches on anything visual in nature, there
|
|||||||
are a few additional guidelines to follow:
|
are a few additional guidelines to follow:
|
||||||
|
|
||||||
* Include screenshots in your ticket which are the visual equivalent of a
|
* Include screenshots in your ticket which are the visual equivalent of a
|
||||||
minimal testcase. Show off the issue, not the crazy customizations
|
minimal test case. Show off the issue, not the crazy customizations
|
||||||
you've made to your browser.
|
you've made to your browser.
|
||||||
|
|
||||||
* If the issue is difficult to show off using a still image, consider
|
* If the issue is difficult to show off using a still image, consider
|
||||||
capturing a *brief* screencast. If your software permits it, capture only
|
capturing a *brief* screencast. If your software permits it, capture only
|
||||||
the relevant area of the screen.
|
the relevant area of the screen.
|
||||||
|
|
||||||
* If you're offering a patch which changes the look or behavior of Django's
|
* If you're offering a patch that changes the look or behavior of Django's
|
||||||
UI, you **must** attach before *and* after screenshots/screencasts.
|
UI, you **must** attach before *and* after screenshots/screencasts.
|
||||||
Tickets lacking these are difficult for triagers to assess quickly.
|
Tickets lacking these are difficult for triagers to assess quickly.
|
||||||
|
|
||||||
@ -109,7 +109,7 @@ part of that. Here are some tips on how to make a request most effectively:
|
|||||||
achieving the same thing.
|
achieving the same thing.
|
||||||
|
|
||||||
If there's a consensus agreement on the feature, then it's appropriate to
|
If there's a consensus agreement on the feature, then it's appropriate to
|
||||||
create a ticket. Include a link the discussion on |django-developers| in the
|
create a ticket. Include a link to the discussion on |django-developers| in the
|
||||||
ticket description.
|
ticket description.
|
||||||
|
|
||||||
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
|
||||||
|
@ -16,8 +16,8 @@ requests.
|
|||||||
|
|
||||||
When committing a pull request, make sure each individual commit matches the
|
When committing a pull request, make sure each individual commit matches the
|
||||||
commit guidelines described below. Contributors are expected to provide the
|
commit guidelines described below. Contributors are expected to provide the
|
||||||
best pull requests possible. In practice however, mergers - who will likely be
|
best pull requests possible. In practice mergers - who will likely be more
|
||||||
more familiar with the commit guidelines - may decide to bring a commit up to
|
familiar with the commit guidelines - may decide to bring a commit up to
|
||||||
standard themselves.
|
standard themselves.
|
||||||
|
|
||||||
You may want to have Jenkins or GitHub actions test the pull request with one
|
You may want to have Jenkins or GitHub actions test the pull request with one
|
||||||
@ -211,7 +211,7 @@ Nobody's perfect; mistakes will be committed.
|
|||||||
But try very hard to ensure that mistakes don't happen. Just because we have a
|
But try very hard to ensure that mistakes don't happen. Just because we have a
|
||||||
reversion policy doesn't relax your responsibility to aim for the highest
|
reversion policy doesn't relax your responsibility to aim for the highest
|
||||||
quality possible. Really: double-check your work, or have it checked by
|
quality possible. Really: double-check your work, or have it checked by
|
||||||
another merger, **before** you commit it in the first place!
|
another merger **before** you commit it in the first place!
|
||||||
|
|
||||||
When a mistaken commit is discovered, please follow these guidelines:
|
When a mistaken commit is discovered, please follow these guidelines:
|
||||||
|
|
||||||
|
@ -26,7 +26,7 @@ The work on Django itself falls into three major areas:
|
|||||||
|
|
||||||
**Localizing Django** 🗺️
|
**Localizing Django** 🗺️
|
||||||
Django is translated into over 100 languages - There's even some
|
Django is translated into over 100 languages - There's even some
|
||||||
translation for Klingon?! The i18n team are always looking for translators
|
translation for Klingon?! The i18n team is always looking for translators
|
||||||
to help maintain and increase language reach.
|
to help maintain and increase language reach.
|
||||||
|
|
||||||
See :doc:`localizing` to help translate Django.
|
See :doc:`localizing` to help translate Django.
|
||||||
|
@ -16,7 +16,7 @@ coordinated at `Transifex`_.
|
|||||||
|
|
||||||
If you find an incorrect translation or want to discuss specific translations,
|
If you find an incorrect translation or want to discuss specific translations,
|
||||||
go to the `Django project page`_. If you would like to help out with
|
go to the `Django project page`_. If you would like to help out with
|
||||||
translating or add a language that isn't yet translated, here's what to do:
|
translating or adding a language that isn't yet translated, here's what to do:
|
||||||
|
|
||||||
* Introduce yourself on the `Django internationalization forum`_.
|
* Introduce yourself on the `Django internationalization forum`_.
|
||||||
|
|
||||||
@ -35,9 +35,9 @@ translating or add a language that isn't yet translated, here's what to do:
|
|||||||
procedural problems and handle the actual translation process.
|
procedural problems and handle the actual translation process.
|
||||||
|
|
||||||
* Once you are a member of a team choose the translation resource you
|
* Once you are a member of a team choose the translation resource you
|
||||||
want to update on the team page. For example the "core" resource refers
|
want to update on the team page. For example, the "core" resource refers
|
||||||
to the translation catalog that contains all non-contrib translations.
|
to the translation catalog that contains all non-contrib translations.
|
||||||
Each of the contrib apps also have a resource (prefixed with "contrib").
|
Each of the contrib apps also has a resource (prefixed with "contrib").
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
For more information about how to use Transifex, read the
|
For more information about how to use Transifex, read the
|
||||||
|
@ -148,8 +148,8 @@ some advice to make your work on Django more useful and rewarding.
|
|||||||
ensure that the *Needs tests*, *Needs documentation*, and *Patch needs
|
ensure that the *Needs tests*, *Needs documentation*, and *Patch needs
|
||||||
improvement* flags are unchecked once you've addressed all review comments.
|
improvement* flags are unchecked once you've addressed all review comments.
|
||||||
|
|
||||||
Remember that Django has an 8 month release cycle, so there's plenty of time
|
Remember that Django has an eight-month release cycle, so there's plenty of
|
||||||
for your patch to be reviewed.
|
time for your patch to be reviewed.
|
||||||
|
|
||||||
Finally, a well-timed reminder can help. See :ref:`contributing code FAQ
|
Finally, a well-timed reminder can help. See :ref:`contributing code FAQ
|
||||||
<new-contributors-faq>` for ideas here.
|
<new-contributors-faq>` for ideas here.
|
||||||
|
@ -6,10 +6,10 @@ 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
|
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
|
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
|
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
|
your help to sort out one from the other, and in the end, we all benefit
|
||||||
together.
|
together.
|
||||||
|
|
||||||
Like all gardens, we can aspire to perfection but in reality there's no such
|
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.
|
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
|
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
|
intentions -- fertilize the weeds and poison the roses. It's the job of the
|
||||||
@ -154,7 +154,7 @@ Someday/Maybe
|
|||||||
-------------
|
-------------
|
||||||
|
|
||||||
This stage isn't shown on the diagram. It's used sparingly to keep track of
|
This stage isn't shown on the diagram. It's used sparingly to keep track of
|
||||||
high-level ideas or long term feature requests.
|
high-level ideas or long-term feature requests.
|
||||||
|
|
||||||
These tickets are uncommon and overall less useful since they don't describe
|
These tickets are uncommon and overall less useful since they don't describe
|
||||||
concrete actionable issues. They are enhancement requests that we might
|
concrete actionable issues. They are enhancement requests that we might
|
||||||
@ -227,7 +227,7 @@ easier to find.
|
|||||||
Severity
|
Severity
|
||||||
--------
|
--------
|
||||||
|
|
||||||
The *severity* attribute is used to identify blockers, that is, issues which
|
The *severity* attribute is used to identify blockers, that is, issues that
|
||||||
should get fixed before releasing the next version of Django. Typically those
|
should get fixed before releasing the next version of Django. Typically those
|
||||||
issues are bugs causing regressions from earlier versions or potentially
|
issues are bugs causing regressions from earlier versions or potentially
|
||||||
causing severe data losses. This attribute is quite rarely used and the vast
|
causing severe data losses. This attribute is quite rarely used and the vast
|
||||||
@ -256,7 +256,7 @@ Keywords
|
|||||||
--------
|
--------
|
||||||
|
|
||||||
With this field you may label a ticket with multiple keywords. This can be
|
With this field you may label a ticket with multiple keywords. This can be
|
||||||
useful, for example, to group several tickets of a same theme. Keywords can
|
useful, for example, to group several tickets on the same theme. Keywords can
|
||||||
either be comma or space separated. Keyword search finds the keyword string
|
either be comma or space separated. Keyword search finds the keyword string
|
||||||
anywhere in the keywords. For example, clicking on a ticket with the keyword
|
anywhere in the keywords. For example, clicking on a ticket with the keyword
|
||||||
"form" will yield similar tickets tagged with keywords containing strings such
|
"form" will yield similar tickets tagged with keywords containing strings such
|
||||||
@ -306,7 +306,7 @@ A ticket can be resolved in a number of ways:
|
|||||||
submit support queries as tickets).
|
submit support queries as tickets).
|
||||||
|
|
||||||
* wontfix
|
* wontfix
|
||||||
Used when a someone decides that the request isn't appropriate for
|
Used when someone decides that the request isn't appropriate for
|
||||||
consideration in Django. Sometimes a ticket is closed as "wontfix" with a
|
consideration in Django. Sometimes a ticket is closed as "wontfix" with a
|
||||||
request for the reporter to start a discussion on the |django-developers|
|
request for the reporter to start a discussion on the |django-developers|
|
||||||
mailing list if they feel differently from the rationale provided by the
|
mailing list if they feel differently from the rationale provided by the
|
||||||
@ -393,7 +393,7 @@ However, we do ask the following of all general community members working in
|
|||||||
the ticket database:
|
the ticket database:
|
||||||
|
|
||||||
* Please **don't** promote your own tickets to "Ready for checkin". You
|
* Please **don't** promote your own tickets to "Ready for checkin". You
|
||||||
may mark other people's tickets which you've reviewed as "Ready for
|
may mark other people's tickets that you've reviewed as "Ready for
|
||||||
checkin", but you should get at minimum one other community member to
|
checkin", but you should get at minimum one other community member to
|
||||||
review a patch that you submit.
|
review a patch that you submit.
|
||||||
|
|
||||||
@ -437,9 +437,9 @@ Next, we mark the current point in history as being "bad" since the test fails::
|
|||||||
|
|
||||||
Now, we need to find a point in git history before the regression was
|
Now, we need to find a point in git history before the regression was
|
||||||
introduced (i.e. a point where the test passes). Use something like
|
introduced (i.e. a point where the test passes). Use something like
|
||||||
``git checkout HEAD~100`` to checkout an earlier revision (100 commits earlier,
|
``git checkout HEAD~100`` to check out an earlier revision (100 commits earlier,
|
||||||
in this case). Check if the test fails. If so, mark that point as "bad"
|
in this case). Check if the test fails. If so, mark that point as "bad"
|
||||||
(``git bisect bad``), then checkout an earlier revision and recheck. Once you
|
(``git bisect bad``), then check out an earlier revision and recheck. Once you
|
||||||
find a revision where your test passes, mark it as "good"::
|
find a revision where your test passes, mark it as "good"::
|
||||||
|
|
||||||
$ git bisect good
|
$ git bisect good
|
||||||
|
@ -2,7 +2,7 @@
|
|||||||
Writing documentation
|
Writing documentation
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
We place a high importance on consistency and readability of documentation.
|
We place high importance on the consistency and readability of documentation.
|
||||||
After all, Django was created in a journalism environment! So we treat our
|
After all, Django was created in a journalism environment! So we treat our
|
||||||
documentation like we treat our code: we aim to improve it as often as
|
documentation like we treat our code: we aim to improve it as often as
|
||||||
possible.
|
possible.
|
||||||
@ -29,7 +29,7 @@ Django release.
|
|||||||
If you'd like to start contributing to our docs, get the development version of
|
If you'd like to start contributing to our docs, get the development version of
|
||||||
Django from the source code repository
|
Django from the source code repository
|
||||||
(see :ref:`installing-development-version`). The development version has the
|
(see :ref:`installing-development-version`). The development version has the
|
||||||
latest-and-greatest documentation, just as it has latest-and-greatest code.
|
latest-and-greatest documentation, just as it has the latest-and-greatest code.
|
||||||
We also backport documentation fixes and improvements, at the discretion of the
|
We also backport documentation fixes and improvements, at the discretion of the
|
||||||
merger, to the last release branch. That's because it's highly advantageous to
|
merger, to the last release branch. That's because it's highly advantageous to
|
||||||
have the docs for the last release be up-to-date and correct (see
|
have the docs for the last release be up-to-date and correct (see
|
||||||
@ -92,7 +92,7 @@ The documentation is organized into several categories:
|
|||||||
Providing background context helps a newcomer connect the topic to things
|
Providing background context helps a newcomer connect the topic to things
|
||||||
that they already know.
|
that they already know.
|
||||||
|
|
||||||
* :doc:`Reference guides </ref/index>` contain technical reference for APIs.
|
* :doc:`Reference guides </ref/index>` contain technical references for APIs.
|
||||||
They describe the functioning of Django's internal machinery and instruct in
|
They describe the functioning of Django's internal machinery and instruct in
|
||||||
its use.
|
its use.
|
||||||
|
|
||||||
@ -120,7 +120,7 @@ Writing style
|
|||||||
=============
|
=============
|
||||||
|
|
||||||
When using pronouns in reference to a hypothetical person, such as "a user with
|
When using pronouns in reference to a hypothetical person, such as "a user with
|
||||||
a session cookie", gender neutral pronouns (they/their/them) should be used.
|
a session cookie", gender-neutral pronouns (they/their/them) should be used.
|
||||||
Instead of:
|
Instead of:
|
||||||
|
|
||||||
* he or she... use they.
|
* he or she... use they.
|
||||||
@ -351,7 +351,7 @@ Documenting new features
|
|||||||
Our policy for new features is:
|
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
|
clearly designates the features that are only available in the Django
|
||||||
development version. Assume documentation readers are using the latest
|
development version. Assume documentation readers are using the latest
|
||||||
release, not the development version.
|
release, not the development version.
|
||||||
|
|
||||||
@ -359,7 +359,7 @@ Our preferred way for marking new features is by prefacing the features'
|
|||||||
documentation with: "``.. versionadded:: X.Y``", followed by a mandatory
|
documentation with: "``.. versionadded:: X.Y``", followed by a mandatory
|
||||||
blank line and an optional description (indented).
|
blank line and an optional description (indented).
|
||||||
|
|
||||||
General improvements, or other changes to the APIs that should be emphasized
|
General improvements or other changes to the APIs that should be emphasized
|
||||||
should use the "``.. versionchanged:: X.Y``" directive (with the same format
|
should use the "``.. versionchanged:: X.Y``" directive (with the same format
|
||||||
as the ``versionadded`` mentioned above.
|
as the ``versionadded`` mentioned above.
|
||||||
|
|
||||||
@ -461,7 +461,7 @@ example:
|
|||||||
You can find both in the :doc:`settings reference document
|
You can find both in the :doc:`settings reference document
|
||||||
</ref/settings>`.
|
</ref/settings>`.
|
||||||
|
|
||||||
We use the Sphinx :rst:role:`doc` cross reference element when we want to
|
We use the Sphinx :rst:role:`doc` cross-reference element when we want to
|
||||||
link to another document as a whole and the :rst:role:`ref` element when
|
link to another document as a whole and the :rst:role:`ref` element when
|
||||||
we want to link to an arbitrary location in a document.
|
we want to link to an arbitrary location in a document.
|
||||||
|
|
||||||
@ -531,7 +531,7 @@ Entries that have a status of "broken" need to be fixed. Those that have a
|
|||||||
status of "redirected" may need to be updated to point to the canonical
|
status of "redirected" may need to be updated to point to the canonical
|
||||||
location, e.g. the scheme has changed ``http://`` → ``https://``. In certain
|
location, e.g. the scheme has changed ``http://`` → ``https://``. In certain
|
||||||
cases, we do not want to update a "redirected" link, e.g. a rewrite to always
|
cases, we do not want to update a "redirected" link, e.g. a rewrite to always
|
||||||
point to the latest or stable version of documentation, e.g. ``/en/stable/`` →
|
point to the latest or stable version of the documentation, e.g. ``/en/stable/`` →
|
||||||
``/en/3.2/``.
|
``/en/3.2/``.
|
||||||
|
|
||||||
Translating documentation
|
Translating documentation
|
||||||
|
Loading…
Reference in New Issue
Block a user