docs: add Humanizer 4 release guides - #1898
Merged
Merged
Conversation
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe documentation site adds a Humanizer 4 migration guide and “What’s new” page. It updates links, navigation, redirects, tests, and historical version exclusions. The previous preview migration guide is removed. ChangesHumanizer 4 documentation
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
Suggested labels: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds Humanizer 4 “release guide” documentation to the Docusaurus site: a curated evaluator-focused “What’s New” page plus a detailed migration guide for upgrading from Humanizer 3.0.10, and wires them into navigation/redirect/version-history overlays.
Changes:
- Add
docs/whats-new(“What’s new in Humanizer 4”) anddocs/upgrading/version-4-migration(“Upgrade from Humanizer 3.0.10 to Humanizer 4”). - Update sidebars + upgrading index/docs index links to point at the new pages, and delete the old
upgrading/main-previewdoc. - Update redirect + historical overlay exclusion rules, and add a unit test to gate the “What’s New” page shape/content.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| website/docs/whats-new/index.mdx | New curated “What’s New in Humanizer 4” page for evaluators. |
| website/docs/upgrading/version-4-migration.mdx | New detailed migration guide replacing the prior preview page. |
| website/docs/upgrading/main-preview.mdx | Removed obsolete preview migration page. |
| website/docs/upgrading/index.mdx | Updates upgrade hub links to the new migration guide. |
| website/docs/index.md | Adds top-level entry points for What’s New + upgrade guide. |
| website/sidebars.json | Adds “What’s New” to the sidebar and swaps upgrading link to version-4-migration. |
| website/redirects.json | Redirects old preview upgrade URL to the new migration route. |
| website/tests/whatsNew.test.mjs | Adds unit coverage to enforce Whats New structure + local-link validity. |
| website/version-overrides/3.0.10/overlay.json | Excludes current-v4 pages from 3.0.10 historical overlays. |
| website/version-overrides/3.0.8/overlay.json | Excludes current-v4 pages from 3.0.8 historical overlays. |
| website/version-overrides/3.0.1/overlay.json | Excludes current-v4 pages from 3.0.1 historical overlays. |
| website/version-overrides/2.14.1/overlay.json | Excludes current-v4 pages from 2.14.1 historical overlays. |
| website/version-overrides/2.13.14/overlay.json | Excludes current-v4 pages from 2.13.14 historical overlays. |
| website/version-overrides/2.11.10/overlay.json | Excludes current-v4 pages from 2.11.10 historical overlays. |
| website/version-overrides/2.10.1/overlay.json | Excludes current-v4 pages from 2.10.1 historical overlays. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6f84d541b5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
10 tasks
clairernovotny
force-pushed
the
codex/docs-v4-release-guides
branch
from
July 30, 2026 19:50
6f84d54 to
e293f92
Compare
clairernovotny
changed the base branch from
codex/docs-v4-foundation
to
codex/docs-v4-reference-contributors
July 30, 2026 19:50
clairernovotny
force-pushed
the
codex/docs-v4-reference-contributors
branch
from
July 30, 2026 20:32
5df4820 to
5c6e2f2
Compare
clairernovotny
force-pushed
the
codex/docs-v4-release-guides
branch
from
July 30, 2026 20:32
e293f92 to
874a33c
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
clairernovotny
force-pushed
the
codex/docs-v4-reference-contributors
branch
from
July 31, 2026 19:21
8285732 to
7b1f039
Compare
clairernovotny
changed the base branch from
codex/docs-v4-reference-contributors
to
main
July 31, 2026 19:53
clairernovotny
force-pushed
the
codex/docs-v4-release-guides
branch
from
July 31, 2026 20:17
b5583d6 to
54e8ddd
Compare
There was a problem hiding this comment.
🧹 Nitpick comments (3)
website/tests/whatsNew.test.mjs (2)
21-22: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueThe two regexes can be bypassed by valid MDX link and fence forms.
Line 22 matches only a bare
```csharpline. A fence written as```csharp title="Example.cs"or as```csdoes not count, so the one-example-per-section rule silently passes. Line 38 captures only links that start with../, so a./or/docs/...link on this page is never checked for existence. Tighten both patterns if the rules must hold for every authoring form.♻️ Proposed pattern widening
- assert((section.match(/^```csharp$/gm) ?? []).length <= 1); + assert((section.match(/^```(?:csharp|cs)\b.*$/gm) ?? []).length <= 1);- const localLinks = [...page.matchAll(/\[[^\]]+\]\((\.\.\/[^)]+)\)/g)] + const localLinks = [...page.matchAll(/\[[^\]]+\]\((\.{1,2}\/[^)]+)\)/g)] .map((match) => match[1].split('#', 1)[0]);Also applies to: 38-39
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@website/tests/whatsNew.test.mjs` around lines 21 - 22, Update the section fence-count regex in whatsNew.test.mjs to recognize both csharp and cs language labels, including optional fence metadata such as title attributes. Also widen the link-matching logic near the section checks to validate relative ./ links and root-relative /docs/... links, not only ../ links.
18-22: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd failure messages to the bare assertions and report the failing link.
Lines 19, 22, and 41 assert without a message. A failure prints only the expression, so a contributor must read the test to learn the budget. Line 42 has the same problem:
Promise.allsurfaces oneENOENTwithout naming the link. Line 34 already shows the better pattern.♻️ Proposed diagnosability fix
const words = page.match(/\b[\p{L}\p{N}][\p{L}\p{N}'’-]*\b/gu) ?? []; - assert(words.length >= 550 && words.length <= 1000); + assert( + words.length >= 550 && words.length <= 1000, + `Overview word count ${words.length} is outside 550-1000.`); - for (const section of page.split(/^## /m).slice(1)) - assert((section.match(/^```csharp$/gm) ?? []).length <= 1); + for (const section of page.split(/^## /m).slice(1)) { + const fences = (section.match(/^```csharp$/gm) ?? []).length; + const heading = section.split('\n', 1)[0]; + assert(fences <= 1, `Section "${heading}" has ${fences} csharp examples; allow at most 1.`); + }- assert(localLinks.length >= 8); - await Promise.all(localLinks.map((link) => - access(new URL(link, pagePath)))); + assert(localLinks.length >= 8, + `Overview has ${localLinks.length} local links; expected at least 8.`); + await Promise.all(localLinks.map(async (link) => { + try { + await access(new URL(link, pagePath)); + } catch { + assert.fail(`Overview links to a missing file: ${link}`); + } + }));Also applies to: 41-43
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@website/tests/whatsNew.test.mjs` around lines 18 - 22, The assertions in the whats-new test lack actionable failure messages. Update the word-count assertion, the per-section C# fence check in the section loop, and the link-validation assertion around Promise.all to include descriptive messages containing the relevant limits or failing link; preserve the existing validation behavior.website/docs/upgrading/version-4-migration.mdx (1)
344-345: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueLink the issue reference instead of a bare
#1892.Docusaurus does not auto-link bare issue numbers. A reader sees plain text on both lines. Use a full URL so the reference is reachable.
📝 Proposed wording
-The existing classic `Pluralize`, `Singularize`, and `ToQuantity` APIs correct -several English rules. This section does not describe the unreleased localized -inflection surface covered by `#1892`. +The existing classic `Pluralize`, `Singularize`, and `ToQuantity` APIs correct +several English rules. This section does not describe the unreleased localized +inflection surface covered by +[`#1892`](https://github.com/Humanizr/Humanizer/issues/1892).-Do not infer localized-inflection behavior from the current candidate. The -final `#1892` API, resolver, generated data, and package diff must be audited and -added here only after that issue is complete. +Do not infer localized-inflection behavior from the current candidate. The +final [`#1892`](https://github.com/Humanizr/Humanizer/issues/1892) API, resolver, +generated data, and package diff must be audited and added here only after that +issue is complete.Also applies to: 442-444
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@website/docs/upgrading/version-4-migration.mdx` around lines 344 - 345, Replace the bare “#1892” reference in the migration documentation with its full issue URL, and apply the same change to the additional occurrence around the referenced section while preserving the surrounding wording.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@website/docs/upgrading/version-4-migration.mdx`:
- Around line 344-345: Replace the bare “#1892” reference in the migration
documentation with its full issue URL, and apply the same change to the
additional occurrence around the referenced section while preserving the
surrounding wording.
In `@website/tests/whatsNew.test.mjs`:
- Around line 21-22: Update the section fence-count regex in whatsNew.test.mjs
to recognize both csharp and cs language labels, including optional fence
metadata such as title attributes. Also widen the link-matching logic near the
section checks to validate relative ./ links and root-relative /docs/... links,
not only ../ links.
- Around line 18-22: The assertions in the whats-new test lack actionable
failure messages. Update the word-count assertion, the per-section C# fence
check in the section loop, and the link-validation assertion around Promise.all
to include descriptive messages containing the relevant limits or failing link;
preserve the existing validation behavior.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 7ceab76e-3a09-44c8-a5e5-c953f8f1d5a9
📒 Files selected for processing (16)
website/docs/analyzer/index.mdxwebsite/docs/index.mdwebsite/docs/upgrading/index.mdxwebsite/docs/upgrading/main-preview.mdxwebsite/docs/upgrading/version-4-migration.mdxwebsite/docs/whats-new/index.mdxwebsite/redirects.jsonwebsite/sidebars.jsonwebsite/tests/whatsNew.test.mjswebsite/version-overrides/2.10.1/overlay.jsonwebsite/version-overrides/2.11.10/overlay.jsonwebsite/version-overrides/2.13.14/overlay.jsonwebsite/version-overrides/2.14.1/overlay.jsonwebsite/version-overrides/3.0.1/overlay.jsonwebsite/version-overrides/3.0.10/overlay.jsonwebsite/version-overrides/3.0.8/overlay.json
💤 Files with no reviewable changes (1)
- website/docs/upgrading/main-preview.mdx
Member
Author
|
[codex] Reviewed the new CodeRabbit review-body nits against the rebased head. No code change is warranted:
The current head remains approved, with no unresolved review threads. Focused local validation and the combined production/link/browser sequence are green; hosted CI is still running. |
11 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Humanizer 4 now has a curated What's New page for evaluators and a separate migration guide for applications moving from 3.0.10. The migration route preserves the old preview URL, and current navigation/linking points to the durable source path without exposing unfinished API names.
Historical overlays explicitly exclude these current-v4 pages, keeping published snapshots version-specific. This PR is rebased directly onto
mainafter #1897 merged; the analyzer release-guide link is therefore valid without a stacked base.Related: #1892
Validation
pnpm --dir website run test:unit— 52/52 passed.pnpm --dir website run check:content— all seven areas passed.pnpm --dir website run typecheck— passed.pwsh ./tools/docs/verify-upgrade-paths.ps1— every published boundary passed.8c904778c71d8ce5cb4aee48a7f6dc1044acf184before and after moving to the docs: refresh v4 reference and contributor guidance #1897 merge onmain.git diff --check— passed.Checklist
mainafter docs: refresh v4 reference and contributor guidance #1897 merged.