Corrected various typos in contributing docs.
This commit is contained in:
Arslan Noor
Carlton Gibson
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>
|
||||
Adiyat Mubarak <adiyatmubarak@gmail.com>
|
||||
Adnan Umer <u.adnan@outlook.com>
|
||||
Arslan Noor <arslannoorpansota@gmail.com>
|
||||
Adrian Holovaty <adrian@holovaty.com>
|
||||
Adrian Torres <atorresj@redhat.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:
|
||||
|
||||
* 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.
|
||||
|
||||
* If the issue is difficult to show off using a still image, consider
|
||||
capturing a *brief* screencast. If your software permits it, capture only
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
commit guidelines described below. Contributors are expected to provide the
|
||||
best pull requests possible. In practice however, mergers - who will likely be
|
||||
more familiar with the commit guidelines - may decide to bring a commit up to
|
||||
best pull requests possible. In practice mergers - who will likely be more
|
||||
familiar with the commit guidelines - may decide to bring a commit up to
|
||||
standard themselves.
|
||||
|
||||
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
|
||||
reversion policy doesn't relax your responsibility to aim for the highest
|
||||
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:
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ The work on Django itself falls into three major areas:
|
|||
|
||||
**Localizing Django** 🗺️
|
||||
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.
|
||||
|
||||
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,
|
||||
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`_.
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
* 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.
|
||||
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::
|
||||
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
|
||||
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
|
||||
for your patch to be reviewed.
|
||||
Remember that Django has an eight-month release cycle, so there's plenty of
|
||||
time for your patch to be reviewed.
|
||||
|
||||
Finally, a well-timed reminder can help. See :ref:`contributing code FAQ
|
||||
<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
|
||||
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
|
||||
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
|
||||
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
|
||||
|
|
@ -154,7 +154,7 @@ Someday/Maybe
|
|||
-------------
|
||||
|
||||
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
|
||||
concrete actionable issues. They are enhancement requests that we might
|
||||
|
|
@ -227,7 +227,7 @@ easier to find.
|
|||
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
|
||||
issues are bugs causing regressions from earlier versions or potentially
|
||||
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
|
||||
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
|
||||
anywhere in the keywords. For example, clicking on a ticket with the keyword
|
||||
"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).
|
||||
|
||||
* 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
|
||||
request for the reporter to start a discussion on the |django-developers|
|
||||
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:
|
||||
|
||||
* 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
|
||||
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
|
||||
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"
|
||||
(``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"::
|
||||
|
||||
$ git bisect good
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
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
|
||||
documentation like we treat our code: we aim to improve it as often as
|
||||
possible.
|
||||
|
|
@ -29,7 +29,7 @@ Django release.
|
|||
If you'd like to start contributing to our docs, get the development version of
|
||||
Django from the source code repository
|
||||
(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
|
||||
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
|
||||
|
|
@ -92,7 +92,7 @@ The documentation is organized into several categories:
|
|||
Providing background context helps a newcomer connect the topic to things
|
||||
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
|
||||
its use.
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ Writing style
|
|||
=============
|
||||
|
||||
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:
|
||||
|
||||
* he or she... use they.
|
||||
|
|
@ -351,7 +351,7 @@ Documenting new features
|
|||
Our policy for new features is:
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
as the ``versionadded`` mentioned above.
|
||||
|
||||
|
|
@ -461,7 +461,7 @@ example:
|
|||
You can find both in the :doc:`settings reference document
|
||||
</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
|
||||
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
|
||||
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
|
||||
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/``.
|
||||
|
||||
Translating documentation
|
||||
|
|
|
|||
Loading…
Reference in New Issue