Standardize spelling to American English in documentation #9804

p-r-a-v-i-n · 2025-10-21T09:15:06Z

According to DRF language-style the documentation should follow the american english style.

But I have found some British style words or inconsistent spellings like behaviour, customise, initialise, e-mail, Sub-classes in the docs. In this PR I have modified them to DRF style.

I have touched 26 files. and I can understand this is relatively large change. I'm not sure whether DRF team will like my approach or not. but if anything is there I'm happy to adjust.

Note: highlight.pack.js were intentionally not modified.

browniebroke

Can we configure codespell in any way to catch this in the future? We're already using it as pre-commit hook

rest_framework/schemas/generators.py

p-r-a-v-i-n · 2025-10-24T04:25:56Z

Thanks for review and suggestion @browniebroke !

Can we configure codespell in any way to catch this in the future?

That would be great if we configured. I have done small research and i found codespell project directly addresses the British-to-American spelling standardization . The maintainers merged a change to include a dedicated en_GB_to_en_US dictionary (related to codespell-project/codespell/pull/1480). This dictionary is specifically designed to flag common British spellings (like the ones I corrected: initialise, behaviour, etc.) as typos.
for maximum coverage we can also use this regex i found in the discussion.

p-r-a-v-i-n · 2025-10-24T06:01:55Z

I tried locally
by adding args: ["--builtin", "clear,rare,en-GB_to_en-US"] in codespell section.

- repo: https://github.com/codespell-project/codespell
  # Configuration for codespell is in .codespellrc
  rev: v2.4.1
  hooks:
  - id: codespell
    args: ["--builtin", "clear,rare,en-GB_to_en-US"]
    exclude: locale|kickstarter-announcement.md|coreapi-0.1.1.js
    additional_dependencies:
      # python doesn't come with a toml parser prior to 3.11
      - "tomli; python_version < '3.11'"

I got following results:

I would love to work on the configuring codespell hook. Can i raise Seperate PR ? if yes, then which file to be ignored for now?

browniebroke · 2025-10-24T06:55:20Z

Can i raise Seperate PR ? if yes, then which file to be ignored for now?

Yes, sure. Fine by me

p-r-a-v-i-n · 2025-10-24T07:44:10Z

I got following results:

@browniebroke If you go through the image, It detect other words too which i haven't detect in the PR. So Should i update those too ? So It will be in one go.
Also I want to mention that spelling errors were ignored in python code by codespell .
It detect those spelling errors only in the "comments" of python files and ".md" files.

browniebroke · 2025-10-24T10:11:05Z

It detect other words too which i haven't detect in the PR. So Should i update those too ? So It will be in one go.

If you want to, sure. Thinking about it again. Would be nice to update codespell config so it's all done in one go as well... This all feels very much related. Fixing the problem and setting us up for no further changes. Same spirit as updating tests as your fix a bug.

Also I want to mention that spelling errors were ignored in python code. It detect those spelling errors only in the "comments" of python files and ".md" files.

👍🏻 Noted

…tency changes: - Activates the `en-GB_to_en-US` built-in dictionary to flag British spellings - Created codespell-ignore-words.txt file to ignore specific words - include `code` and `names` for comprehensive typo checking in technical contexts. - changed the 'lets' to 'let's'.

browniebroke

Nice work!

deronnax

in two places, a legitimate "lets" (3rd person of "let") was replaced for "let's" ("let us", suggestive form, invitation to do something).

deronnax · 2025-11-23T16:05:53Z

docs/api-guide/authentication.md

 ## Hawk HTTP Authentication

-The [HawkREST][hawkrest] library builds on the [Mohawk][mohawk] library to let you work with [Hawk][hawk] signed requests and responses in your API. [Hawk][hawk] lets two parties securely communicate with each other using messages signed by a shared key. It is based on [HTTP MAC access authentication][mac] (which was based on parts of [OAuth 1.0][oauth-1.0a]).
+The [HawkREST][hawkrest] library builds on the [Mohawk][mohawk] library to let you work with [Hawk][hawk] signed requests and responses in your API. [Hawk][hawk] let's two parties securely communicate with each other using messages signed by a shared key. It is based on [HTTP MAC access authentication][mac] (which was based on parts of [OAuth 1.0][oauth-1.0a]).


the change to let's here is an error, ` was the right form

deronnax · 2025-11-23T16:06:09Z

docs/api-guide/serializers.md

 Often you'll want serializer classes that map closely to Django model definitions.

-The `ModelSerializer` class provides a shortcut that lets you automatically create a `Serializer` class with fields that correspond to the Model fields.
+The `ModelSerializer` class provides a shortcut that let's you automatically create a `Serializer` class with fields that correspond to the Model fields.


same wrong change here.

browniebroke · 2025-11-24T08:22:25Z

in two places, a legitimate "lets" (3rd person of "let") was replaced for "let's" ("let us", suggestive form, invitation to do something).

Good catch! Can someone open a PR to fix these?

p-r-a-v-i-n · 2025-11-24T08:58:49Z

i have open the PR #9833 which will restore this incorrect wording.

browniebroke reviewed Oct 23, 2025

View reviewed changes

rest_framework/schemas/generators.py Outdated Show resolved Hide resolved

Standardize spelling to American English (only in .md files)

f2f5d86

p-r-a-v-i-n force-pushed the standardize-american-english branch from f4e1eaf to f2f5d86 Compare October 24, 2025 05:05

browniebroke changed the title ~~Standardize spelling to American English~~ Standardize spelling to American English in documentation Oct 24, 2025

browniebroke added the Documentation label Oct 24, 2025

browniebroke previously approved these changes Oct 24, 2025

View reviewed changes

p-r-a-v-i-n added 2 commits October 24, 2025 16:52

Update remaining British english spell words to American english style

e429027

p-r-a-v-i-n dismissed browniebroke’s stale review via c79e9ff October 24, 2025 12:10

browniebroke approved these changes Oct 27, 2025

View reviewed changes

auvipy approved these changes Oct 27, 2025

View reviewed changes

auvipy merged commit ade172e into encode:main Oct 27, 2025
7 checks passed

p-r-a-v-i-n deleted the standardize-american-english branch October 28, 2025 10:53

deronnax reviewed Nov 23, 2025

View reviewed changes

p-r-a-v-i-n mentioned this pull request Nov 24, 2025

Fix incorrect “let’s” usages and restore “lets” #9833

Open

Uh oh!

Standardize spelling to American English in documentation #9804

Standardize spelling to American English in documentation #9804

Uh oh!

Conversation

p-r-a-v-i-n commented Oct 21, 2025

Uh oh!

browniebroke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

p-r-a-v-i-n commented Oct 24, 2025

Uh oh!

p-r-a-v-i-n commented Oct 24, 2025

Uh oh!

browniebroke commented Oct 24, 2025

Uh oh!

p-r-a-v-i-n commented Oct 24, 2025

Uh oh!

browniebroke commented Oct 24, 2025

Uh oh!

browniebroke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

deronnax left a comment

Choose a reason for hiding this comment

Uh oh!

deronnax Nov 23, 2025

Choose a reason for hiding this comment

Uh oh!

deronnax Nov 23, 2025

Choose a reason for hiding this comment

Uh oh!

browniebroke commented Nov 24, 2025

Uh oh!

p-r-a-v-i-n commented Nov 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants