-
-
Notifications
You must be signed in to change notification settings - Fork 6.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Upgrade Jest website to Docusaurus v3 #14463
Conversation
✅ Deploy Preview for jestjs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ready to review 🎉
The visual diff reported by Argos between prod and PR looks minimal and mostly false positives
(sometimes it's very subtle and related to font anti-aliasing rendering)
https://app.argos-ci.com/slorber/jest-website-visual-tests
Note, one of the diffs reported is related to a typo that will be fixed by another PR: #14466
README.md
Outdated
<details><summary markdown="span"><strong>Making your Babel config jest-aware</strong></summary> | ||
<details> | ||
<summary markdown="span"><strong>Making your Babel config jest-aware</strong></summary> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In MDX v2 this does not compile.
This is the readme though so not a big deal but I updated it too because mdx docs have the exact same content.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This change can be moved to a preparation PR and would work with both MDX v1 and v2
docs/Configuration.md
Outdated
If you are seeing coverage output such as... | ||
|
||
If you are seeing coverage output such as... |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In MDX v2 not having a line break will wrap the summary in an extra useless paragraph. This leads browsers to ignore the nested summary tag and display the default label instead of the provided one.
CF problem reported by Argos here: https://app.argos-ci.com/slorber/jest-website-visual-tests/builds/11/56882867
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This change can be moved to a preparation PR and would work with both MDX v1 and v2
docs/GettingStarted.md
Outdated
<details><summary markdown="span"><strong>Making your Babel config jest-aware</strong></summary> | ||
<details> | ||
<summary markdown="span"><strong>Making your Babel config jest-aware</strong></summary> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In MDX v2 this does not compile.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This change can be moved to a preparation PR and would work with both MDX v1 and v2
docs/MockFunctionAPI.md
Outdated
:::warning | ||
:::danger |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
:::warning
is a legacy Docusaurus admonition alias that is not documented, see https://docusaurus.io/docs/markdown-features/admonitions
Issue reported by Argos due to default label change: https://app.argos-ci.com/slorber/jest-website-visual-tests/builds/11/56882879
Using :::danger
is the official red admonition name, keep the same label as before
Note: we are going to reintroduce :::warning
soon, but it will be yellow instead of red (facebook/docusaurus#7558)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we wanted this to be yellow. That doesn't currently exist?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The yellow admonition is currently :::caution
.
I'd suggest to change that in another PR: the goal of this PR is to focus on having no regression and not improving things ;)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This change can be moved to a preparation PR and would work with both MDX v1 and v2
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yellow is better!!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
landed that yesterday #14493
The path to a module that can resolve test<->snapshot path. This config option lets you customize where Jest stores snapshot files on disk. | ||
The path to a module that can resolve test\<->snapshot path. This config option lets you customize where Jest stores snapshot files on disk. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In MDX v2 this does not compile. Escaping is a good solution.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@SimenB this can't be extracted as is to a docs prep PR because on MDX v1, \
will stay visible. The only solution that works on MDX v1 + v2 is test<->snapshot
which IMHO is much less maintainable compared to \<->
.
For this reason I think it's better to keep this change in this PR
The changes for mdx 2 - can they land separately, or do they not work for v1? Just so we reduce this PR down as much as possible down to just the version change |
yarn.lock
Outdated
@@ -5269,6 +5808,17 @@ __metadata: | |||
languageName: node | |||
linkType: hard | |||
|
|||
"@types/react@npm:>=16, @types/react@npm:^18.2.21": |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Seems this is causing issues. Would a dedupe
help?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I ran yarn dedupe but it doesn't seem to fix CI failures.
I don't really know what's the problem here 😅 any idea?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Tried to fix it, seems to work but dedupe actually creates problems 😅
I can do that, this is what I did for React-Native (facebook/react-native-website#3780) with 2 "preparation PRs" because there were a lot more content changes to make compared to Jest.
Unfortunately there's a tradeoff, and indeed adapting the content to make it work for both MDX v1 and MDX v2 is not always the "ideal solution". For example: Under MDX v1: the If you want something that works with both versions, you would have to use a less ideal form: So, it's up to you if we should either:
|
This reverts commit b547523.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks like I was able to make all the tests pass.
@@ -21,6 +21,7 @@ | |||
"@types/babel__template": "^7.0.2", | |||
"@types/node": "~14.14.45", | |||
"@types/which": "^3.0.0", | |||
"@types/ws": "8.5.1", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks like the newer 8.5.5 is causing failures due to a breaking change (a type became non-generic while it was before)
@@ -172,6 +173,7 @@ | |||
}, | |||
"resolutions": { | |||
"@types/node": "~14.14.45", | |||
"@types/react": "^18.2.21", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is the only way I was able to avoid TS issues. Other alternatives can be explored (reduce hoisting etc) but that looks fine to me?
React.createElement(Consumer, null, () => | ||
React.createElement('div', null, 'child'), | ||
), | ||
React.createElement(Consumer, { | ||
children: () => React.createElement('div', null, 'child'), | ||
}), | ||
), | ||
).toBe('<Context.Consumer>\n [Function anonymous]\n</Context.Consumer>'); | ||
).toBe('<Context.Consumer>\n [Function children]\n</Context.Consumer>'); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
With React 18 it seems ReactNode (3rd arg) doesn't accept a function anymore so I replaced it with props.children
Yeah, that seems ideal 👍 I'll take a look at the React types stuff, but your solution might be the right one |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
do most content preparation in upfront PRs, and keep some content changes like the one above for the v3 upgrade PR
Yeah, that seems ideal 👍
Note there are only 3 docs changes, of which only 2 can be moved to a docs preparation PR without bad tradeoffs
All the other docs changes are exactly the same changes, and related to versioned docs.
Do you still want me to extract these 2 docs changes (+ versioned docs) in a separate preparation PR?
The path to a module that can resolve test<->snapshot path. This config option lets you customize where Jest stores snapshot files on disk. | ||
The path to a module that can resolve test\<->snapshot path. This config option lets you customize where Jest stores snapshot files on disk. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@SimenB this can't be extracted as is to a docs prep PR because on MDX v1, \
will stay visible. The only solution that works on MDX v1 + v2 is test<->snapshot
which IMHO is much less maintainable compared to \<->
.
For this reason I think it's better to keep this change in this PR
README.md
Outdated
<details><summary markdown="span"><strong>Making your Babel config jest-aware</strong></summary> | ||
<details> | ||
<summary markdown="span"><strong>Making your Babel config jest-aware</strong></summary> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This change can be moved to a preparation PR and would work with both MDX v1 and v2
docs/Configuration.md
Outdated
If you are seeing coverage output such as... | ||
|
||
If you are seeing coverage output such as... |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This change can be moved to a preparation PR and would work with both MDX v1 and v2
docs/GettingStarted.md
Outdated
<details><summary markdown="span"><strong>Making your Babel config jest-aware</strong></summary> | ||
<details> | ||
<summary markdown="span"><strong>Making your Babel config jest-aware</strong></summary> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This change can be moved to a preparation PR and would work with both MDX v1 and v2
docs/MockFunctionAPI.md
Outdated
:::warning | ||
:::danger |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This change can be moved to a preparation PR and would work with both MDX v1 and v2
Ended up with #14470, so the approach in this PR seems fine for now as that needs to wait for Jest 30. |
Yeah, that'd be great, thanks! |
website/package.json
Outdated
"react-github-btn": "^1.3.0", | ||
"react-lite-youtube-embed": "^2.2.2", | ||
"react-markdown": "^8.0.0" | ||
}, | ||
"devDependencies": { | ||
"@babel/core": "^7.11.6", | ||
"@crowdin/cli": "^3.5.2", | ||
"@docusaurus/module-type-aliases": "^2.0.0", | ||
"@docusaurus/module-type-aliases": "0.0.0-5658", | ||
"@tsconfig/docusaurus": "^1.0.5", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
maybe bump this as well?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What do you mean? bump to what value?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
v2 has been released
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
??? but it's a Docusaurus dependency, we want it to be v3 (canary) like the other docusaurus dependencies.
All official Docusaurus deps should use the exact same versions.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ahh! thought you were talking about the module above.
Actually you are right I forgot something, we are using a new official package @docusaurus/tsconfig
now
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
just remove it based on tsconfig/bases#196?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ahh! thought you were talking about the module above.
Actually you are right I forgot something, we are using a new official package
@docusaurus/tsconfig
now
👍
Let me know if it looks good to you. It seems the tests are failing on main now so not sure if this PR is ok or introduces new failures. It's probably due to Node 20.6 that apparently breaks a few things in the ecosystem. However this test is failing too: https://github.com/jestjs/jest/actions/runs/6110952563/job/16585434858?pr=14463 Maybe this timeout is expected and it's a flaky test? |
Just flake, yeah. And node 20 is broken due to nodejs/node#49497 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
looks great from I can tell from clicking around in the preview. Thanks for doing this!
hah #14496 |
This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
PR to upgrade to Docusaurus v3 canary
See also: Prepare website docs content for MDX v2 and Docusaurus v3
Deploy preview: https://deploy-preview-14463--jestjs.netlify.app/
Argos visual tests
Related links: