From dcf6cbd67c6bebf2ce6e0afec3592b471bcf1aeb Mon Sep 17 00:00:00 2001 From: Andrei Matei Date: Mon, 15 Jun 2026 13:24:04 +0100 Subject: [PATCH 1/4] feat(ipa): enrich IPA-100 Language with Guideline components CLOUDP-399880 --- ipa/general/0100.md | 33 ------------- ipa/general/0100.mdx | 107 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+), 33 deletions(-) delete mode 100644 ipa/general/0100.md create mode 100644 ipa/general/0100.mdx diff --git a/ipa/general/0100.md b/ipa/general/0100.md deleted file mode 100644 index 0ac5c89..0000000 --- a/ipa/general/0100.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -id: 100 -state: adopt ---- - -# IPA-100: Language - -Developers worldwide use MongoDB, and many customers who don't speak English as -their first language consume our APIs. It is important to avoid any possible -confusion across different idioms and colloquialisms unifying to a common -language. - -## Guidance - -API producers **must** use American English across the API. - -This includes but is not limited to: - -- Resource names -- Field names -- Descriptions -- Enum values - -**Example:** “canceled” over -[cancelled](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Cloud-Backups/operation/createBackupExportJob). - -The MongoDB Style Guide uses the Merriam-Webster’s Collegiate Dictionary. 11th -ed. Springfield, MA: Merriam-Webster, 2003. Continually updated at -[https://www.merriam-webster.com/](https://www.merriam-webster.com/). - -## Further Reading - -[MongoDB Meta Documentation](https://www.mongodb.com/docs/meta/style-guide/terminology/general-term-guidelines/use-consistent-terms/#use-consistent-terminology) diff --git a/ipa/general/0100.mdx b/ipa/general/0100.mdx new file mode 100644 index 0000000..67fa438 --- /dev/null +++ b/ipa/general/0100.mdx @@ -0,0 +1,107 @@ +--- +id: 100 +state: adopt +--- + +# IPA-100: Language + +Developers worldwide use MongoDB, and many customers who don't speak English as +their first language consume our APIs. It is important to avoid any possible +confusion across different idioms and colloquialisms unifying to a common +language. + +## Guidance + +API producers **must** use American English across the API. + +This includes but is not limited to: + +- Resource names +- Field names +- Descriptions +- Enum values + +**Example:** “canceled” over +[cancelled](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Cloud-Backups/operation/createBackupExportJob). + +The MongoDB Style Guide uses the Merriam-Webster’s Collegiate Dictionary. 11th +ed. Springfield, MA: Merriam-Webster, 2003. Continually updated at +[https://www.merriam-webster.com/](https://www.merriam-webster.com/). + + + + + +API producers **must** use American English for all user-facing text in the API +specification, including resource names, field names, descriptions, summaries, +and enum values. + + + +```yaml +paths: + /api/atlas/v2/groups/{groupId}/clusters/{clusterName}/backup/exports: + post: + summary: Create One Backup Export Job + operationId: createBackupExportJob + description: >- + Creates one export job for the specified backup snapshot. The job is + canceled if it does not complete within 24 hours. + responses: + "200": + description: OK +``` + + + Uses the American English spelling "canceled" (one "l") in the user-facing + description. + + + + + + +```yaml +paths: + /api/atlas/v2/groups/{groupId}/clusters/{clusterName}/backup/exports: + post: + summary: Create One Backup Export Job + operationId: createBackupExportJob + description: >- + Creates one export job for the specified backup snapshot. The job is + cancelled if it does not complete within 24 hours. + responses: + "200": + description: OK +``` + + + Uses the British English spelling "cancelled" (double "l"). American English + uses "canceled". + + + + + + + Scan every user-facing string in the specification: descriptions, summaries, + enum values, resource names, and field names. + + + For each string, check for common British English spellings (e.g., + "cancelled", "colour", "authorise", "behaviour", "organisation"). + + + Consult Merriam-Webster's dictionary for the preferred American English + form. + + Flag any non-American spelling as a violation. + + + + + + +## Further Reading + +[MongoDB Meta Documentation](https://www.mongodb.com/docs/meta/style-guide/terminology/general-term-guidelines/use-consistent-terms/#use-consistent-terminology) From 1011fa120e0cadcf066125250b3139fa4e9dfeeb Mon Sep 17 00:00:00 2001 From: Andrei Matei Date: Tue, 16 Jun 2026 11:10:10 +0100 Subject: [PATCH 2/4] refactor(ipa): streamline IPA-100 guideline and mark it lintable CLOUDP-399880 --- ipa/general/0100.mdx | 82 ++++++++------------------------------------ 1 file changed, 15 insertions(+), 67 deletions(-) diff --git a/ipa/general/0100.mdx b/ipa/general/0100.mdx index 67fa438..ea00042 100644 --- a/ipa/general/0100.mdx +++ b/ipa/general/0100.mdx @@ -10,8 +10,16 @@ their first language consume our APIs. It is important to avoid any possible confusion across different idioms and colloquialisms unifying to a common language. +:::note The MongoDB Style Guide uses the Merriam-Webster’s Collegiate +Dictionary. 11th ed. Springfield, MA: Merriam-Webster, 2003. Continually updated +at [https://www.merriam-webster.com/](https://www.merriam-webster.com/). ::: + ## Guidance + + + + API producers **must** use American English across the API. This includes but is not limited to: @@ -21,83 +29,23 @@ This includes but is not limited to: - Descriptions - Enum values -**Example:** “canceled” over -[cancelled](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Cloud-Backups/operation/createBackupExportJob). - -The MongoDB Style Guide uses the Merriam-Webster’s Collegiate Dictionary. 11th -ed. Springfield, MA: Merriam-Webster, 2003. Continually updated at -[https://www.merriam-webster.com/](https://www.merriam-webster.com/). - - - - - -API producers **must** use American English for all user-facing text in the API -specification, including resource names, field names, descriptions, summaries, -and enum values. - ```yaml -paths: - /api/atlas/v2/groups/{groupId}/clusters/{clusterName}/backup/exports: - post: - summary: Create One Backup Export Job - operationId: createBackupExportJob - description: >- - Creates one export job for the specified backup snapshot. The job is - canceled if it does not complete within 24 hours. - responses: - "200": - description: OK +properties: + status: + type: string + enum: + - CANCELED + - COMPLETED ``` - Uses the American English spelling "canceled" (one "l") in the user-facing - description. + Uses the American English spelling "canceled" (one "l") in the enum value. - - -```yaml -paths: - /api/atlas/v2/groups/{groupId}/clusters/{clusterName}/backup/exports: - post: - summary: Create One Backup Export Job - operationId: createBackupExportJob - description: >- - Creates one export job for the specified backup snapshot. The job is - cancelled if it does not complete within 24 hours. - responses: - "200": - description: OK -``` - - - Uses the British English spelling "cancelled" (double "l"). American English - uses "canceled". - - - - - - - Scan every user-facing string in the specification: descriptions, summaries, - enum values, resource names, and field names. - - - For each string, check for common British English spellings (e.g., - "cancelled", "colour", "authorise", "behaviour", "organisation"). - - - Consult Merriam-Webster's dictionary for the preferred American English - form. - - Flag any non-American spelling as a violation. - - From 7eae800ef0eac3d7e871e6af7bfedbdf16d0d12c Mon Sep 17 00:00:00 2001 From: Andrei Matei Date: Tue, 16 Jun 2026 11:39:05 +0100 Subject: [PATCH 3/4] fix(ipa): apply markdown vertical rhythm to body Children of render with Docusaurus' markdown spacing; the .markdown > * rules only match direct children of a markdown container. CLOUDP-399880 --- src/components/ipa/Guideline/index.tsx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/components/ipa/Guideline/index.tsx b/src/components/ipa/Guideline/index.tsx index 6de7733..5b94513 100644 --- a/src/components/ipa/Guideline/index.tsx +++ b/src/components/ipa/Guideline/index.tsx @@ -28,7 +28,11 @@ export function Guideline({ {isInsideGuidelines && }
-
{children}
+ {/* `markdown` makes children inherit Docusaurus' markdown vertical + rhythm (heading/paragraph/list/admonition spacing), since the + `.markdown > *` rules only match direct children of a markdown + container. */} +
{children}
From b9e8b5d08cbf83f49ad07d36d05a0415dbdd90e4 Mon Sep 17 00:00:00 2001 From: Andrei Matei Date: Tue, 16 Jun 2026 11:39:08 +0100 Subject: [PATCH 4/4] refactor(ipa): move dictionary note inside the IPA-100 guideline CLOUDP-399880 --- ipa/general/0100.mdx | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/ipa/general/0100.mdx b/ipa/general/0100.mdx index ea00042..f94d0f7 100644 --- a/ipa/general/0100.mdx +++ b/ipa/general/0100.mdx @@ -10,10 +10,6 @@ their first language consume our APIs. It is important to avoid any possible confusion across different idioms and colloquialisms unifying to a common language. -:::note The MongoDB Style Guide uses the Merriam-Webster’s Collegiate -Dictionary. 11th ed. Springfield, MA: Merriam-Webster, 2003. Continually updated -at [https://www.merriam-webster.com/](https://www.merriam-webster.com/). ::: - ## Guidance @@ -29,6 +25,14 @@ This includes but is not limited to: - Descriptions - Enum values +:::note + +The MongoDB Style Guide uses the Merriam-Webster’s Collegiate Dictionary. 11th +ed. Springfield, MA: Merriam-Webster, 2003. Continually updated at +[https://www.merriam-webster.com/](https://www.merriam-webster.com/). + +::: + ```yaml