Skip to content
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.

Sign up for GitHub

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

Jump to bottom

docs: add troubleshooting steps to migration/upgrade page #9490

Merged
merged 10 commits into from
Apr 18, 2024
Merged

docs: add troubleshooting steps to migration/upgrade page #9490

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
dedb0e4
add troubleshooting steps to migration/upgrade page
homotechsual Nov 1, 2023
c24e53f
Close TabItem and Tabs
homotechsual Nov 1, 2023
30a3b8b
Close second TabItem
homotechsual Nov 1, 2023
334686d
add PowerShell to languages
homotechsual Nov 1, 2023
e30f600
Update index.mdx
Josh-Cena Nov 1, 2023
d53dfe3
prettier
slorber Dec 1, 2023
5d81496
Merge branch 'main' into patch-15
slorber Dec 1, 2023
271efb3
test commit
slorber Dec 1, 2023
c04bb00
Merge branch 'main' into patch-15
slorber Dec 14, 2023
f0bccf6
Update website/docusaurus.config.ts
slorber Apr 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions website/docs/migration/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,42 @@ Docusaurus versioning is based on the `major.minor.patch` scheme and respects [*
import DocCardList from '@theme/DocCardList';

<DocCardList />

## Troubleshooting upgrades

When upgrading Docusaurus you may experience issues caused by mismatching cached dependencies - there are a few troubleshooting steps you should perform to resolve these common issues before reporting a bug or seeking support.

### Run the `clear` command

This CLI command is used to clear a Docusaurus site's generated assets, caches and build artifacts.

```bash npm2yarn
npm run clear
```

### Remove `node_modules` and your lock file(s)

Remove the `node_modules` folder and your package manager's lock file using the following:

<Tabs>
<TabItem label="Bash" value="bash">

```bash
rm -rf node_modules yarn.lock package-lock.json
```

</TabItem>
<TabItem label="PowerShell" value="powershell">

```powershell
@('node_modules','yarn.lock','package-lock.json') | Remove-Item -Force -Recurse -ErrorAction SilentlyContinue
```
Comment on lines +41 to +43
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't find it necessary to document powershell—https://docusaurus.io/docs/i18n/tutorial#translate-the-docs here we don't. Particularly for simple commands like this that can even be done through the file UI, let's keep things simple.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's the primary scripting language of a vast swathe of Docusaurus users who're using Windows, I feel it's helpful to have those examples where they make sense - which they don't in all cases but happy for it not to be included if that's the concensus

Copy link
Contributor

@armano2 armano2 Mar 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

 rm -r node_modules
 rm -r yarn.lock
 rm -r package-lock.json

should work fine with new versions of powershell

PS D:\Projects\docusaurus> rm -r node_modules
PS D:\Projects\docusaurus> rm -r yarn.lock
PS D:\Projects\docusaurus> rm -r package-lock.json
Remove-Item: Cannot find path 'D:\Projects\docusaurus\package-lock.json' because it does not exist.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great to know thanks. Is this really new or most Windows users have it supported?

@homotechsual can you confirm it works for you with rm -rf? if yes I'd rather remove those tabs before merging

Copy link
Contributor

@armano2 armano2 Apr 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it should be supported in most of win 10-11 and in and potentially in older versions of windows if user uses powershell

rm is just a shortcut for Remove-Item

PS D:\> 'rm', 'rmdir', 'rd' | Get-Command

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Alias           rm -> Remove-Item
Alias           rmdir -> Remove-Item
Alias           rd -> Remove-Item

-rf s alittle tricker but if you really want to have f like behaviour you want to use something like rm -r -fo node_modules, but that should not be necessary

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rm works - but the switches don't translate 1-1 on any version of Windows or PowerShell which is why the separate command is needed. You could do rm -r -fo for Windows but then really you still have a different command - but you're just making it needlessly confusing by using an aliased version of the full command I included.

If you guys don't think it needs to be included I get it - I can remove it. I'm just seeing more frequent questions from devs on Windows and all our command examples are linux only. I'm more than happy to widen this effort so it's consistent where it makes sense in a similar method to how we handle providing npm yarn and pnpm examples.


</TabItem>
</Tabs>

Then reinstall packages and regenerate the `lock` file using:

```bash npm2yarn
npm install
```
3 changes: 2 additions & 1 deletion website/docusaurus.config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
* LICENSE file in the root directory of this source tree.
*/
import path from 'path';

// blablablitest

Check failure on line 8 in website/docusaurus.config.ts

View workflow job for this annotation

GitHub Actions / Lint 

Unknown word (blablablitest) -- // blablablitest
slorber marked this conversation as resolved.
Show resolved Hide resolved
import npm2yarn from '@docusaurus/remark-plugin-npm2yarn';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
Expand Down Expand Up @@ -486,6 +486,7 @@
'haskell',
'matlab',
'PHp',
'powershell',
'bash',
'diff',
'json',
Expand Down
Loading