From 5c93a84f44054034f495267ff2400a5de69a4fc1 Mon Sep 17 00:00:00 2001 From: Arslan Noor Date: Thu, 30 Jun 2022 10:37:54 +0200 Subject: [PATCH] Corrected various typos in contributing docs. --- AUTHORS | 1 + .../contributing/bugs-and-features.txt | 6 +++--- .../internals/contributing/committing-code.txt | 6 +++--- docs/internals/contributing/index.txt | 2 +- docs/internals/contributing/localizing.txt | 6 +++--- .../contributing/new-contributors.txt | 4 ++-- .../contributing/triaging-tickets.txt | 18 +++++++++--------- .../contributing/writing-documentation.txt | 16 ++++++++-------- 8 files changed, 30 insertions(+), 29 deletions(-) diff --git a/AUTHORS b/AUTHORS index 7660d3a154..356680682a 100644 --- a/AUTHORS +++ b/AUTHORS @@ -22,6 +22,7 @@ answer newbie questions, and generally made Django that much better: Ade Lee Adiyat Mubarak Adnan Umer + Arslan Noor Adrian Holovaty Adrian Torres Adrien Lemaire diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt index 188fb0ca0e..fdbc78c523 100644 --- a/docs/internals/contributing/bugs-and-features.txt +++ b/docs/internals/contributing/bugs-and-features.txt @@ -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 diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt index ed94ee9609..aab5cf300c 100644 --- a/docs/internals/contributing/committing-code.txt +++ b/docs/internals/contributing/committing-code.txt @@ -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: diff --git a/docs/internals/contributing/index.txt b/docs/internals/contributing/index.txt index f798cae5e7..9d72f4a705 100644 --- a/docs/internals/contributing/index.txt +++ b/docs/internals/contributing/index.txt @@ -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. diff --git a/docs/internals/contributing/localizing.txt b/docs/internals/contributing/localizing.txt index fef9e62db0..9647671b5c 100644 --- a/docs/internals/contributing/localizing.txt +++ b/docs/internals/contributing/localizing.txt @@ -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 diff --git a/docs/internals/contributing/new-contributors.txt b/docs/internals/contributing/new-contributors.txt index 8457f41941..8e81031b32 100644 --- a/docs/internals/contributing/new-contributors.txt +++ b/docs/internals/contributing/new-contributors.txt @@ -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 ` for ideas here. diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt index fe37a20da5..ce60b8ac4e 100644 --- a/docs/internals/contributing/triaging-tickets.txt +++ b/docs/internals/contributing/triaging-tickets.txt @@ -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 diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 97fc87ac15..5303e61517 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -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 ` contain technical reference for APIs. +* :doc:`Reference guides ` 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 `. - 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