docs(admin): update repo testing instructions to reflect v2 (#5845)

* docs: add some details (trivial)

* docs: add easier method (using yarn) to test local repo

* docs: add additional note

* Edits

* Update

Co-authored-by: Josh-Cena <sidachen2003@gmail.com>

admin/local-third-party-project-testing.md

@@ -6,125 +6,78 @@ There are two reasonable ways to use a local version of the Docusaurus npm packa
 
 ## Install from a local Docusaurus repo
 
-> If you want to use the docusaurus init script for testing, you will have to update the `initialize.js` file to point to the local Docusaurus repo instead of installing it from the npm server. In some ways, it is just easier to do the manual steps.
+### Install in an existing project
 
-### Install the package from the Docusaurus repo
-
-```bash
-cd /path/to/testing_project
-mkdir website # if this does not exist already
-cd website
-```
-
-If you do not have a `package.json` file in the `website` directory, create one with the following content:
+Let's say you have an existing project with this snippet inside package.json:
 
 ```json
 {
-  "scripts": {
-    "start": "docusaurus-start",
-    "build": "docusaurus-build",
-    "publish-gh-pages": "docusaurus-publish",
-    "examples": "docusaurus-examples"
+  "dependencies": {
+    "@docusaurus/core": "^2.0.0-beta.8",
+    "@docusaurus/preset-classic": "^2.0.0-beta.8"
   }
 }
 ```
 
-Then:
+Now, you have made changes to @docusaurus/core (this lives in packages/docusaurus) and would like to test the changes. In the local docusaurus repo, run `yarn install`. This will also build the local docusaurus packages and install them within the repo itself:
 
 ```sh
-# Path to your Docusaurus clone
-npm install ../../path/to/docusaurus/
+cd /path/to/local/docusaurus
+# can use yarn build:packages if dependencies have not been modified
+yarn install
 ```
 
-### Clowntown!
-
-Now, we have a bit of clowntown here in the way symlinks are handled. The above `npm install`, creates a `node_modules` directory with a symlink in it. And errors will result if you try to access the local site after starting the server (as you do below). You will get something like this error:
-
-```
-ReferenceError: Unknown plugin "transform-class-properties" specified in "base" at 1, attempted to resolve relative to "/Users/joelm/dev/testing-local-Docusaurus-changes-site/website/core"
+In the existing project, add the local package:
 
+```sh
+cd /path/to/existing/project
+# this can be an absolute or relative path
+yarn add @docusaurus/core@../../local/docusaurus/packages/docusaurus
 ```
 
-So, you should install these packages locally. **Base the versions on the versions defined in the Docusaurus `package.json`**. e.g.,
+Check package.json again and you will find this:
 
-```bash
-# Still in the website directory of the testing project
-npm install babel-plugin-transform-class-properties@^6.24.1
-npm install babel-plugin-transform-object-rest-spread@^6.26.0
-npm install react@^16.4.1
-npm install babel-preset-env@^1.7.0
-npm install babel-preset-react@^6.24.1
+```json
+{
+  "dependencies": {
+    "@docusaurus/core": "../../local/docusaurus/packages/docusaurus",
+    "@docusaurus/preset-classic": "^2.0.0-beta.8"
+  }
+}
 ```
 
-### Test
+If you make further changes to the local docusaurus repo, run `yarn install` inside the existing project so that the changes will be applied.
 
-```bash
-./node_modules/.bin/docusaurus-examples # or whatever you want to test, if anything
-./node_modules/.bin/docusaurus-start
-```
+Note that:
+
+- The format is `scoped-package-name@local/path/to/specific/package/directory`.
+- The last component of the supplied path cannot be a symbolic link, it has to be the package directory itself.
+- If you supplied the wrong directory name, `yarn add` may not complain, but `yarn build` and `yarn start` will fail. To avoid this, check `package.json` inside the package directory to make sure you have the correct path.
+- These commands don't work:
+  ```
+  yarn add @docusaurus/core@../../local/docusaurus/node_modules/@docusaurus/core
+  yarn add file:../../local/docusaurus/packages/docusaurus
+  yarn add link:../../local/docusaurus/packages/docusaurus
+  yarn add ../../local/docusaurus/node_modules/@docusaurus/core
+  yarn add ../../local/docusaurus/packages/docusaurus
+  ```
+- You cannot use `npm install` instead of `yarn add` for this purpose.
+- `yarn link` is very likely to fail with react, unless you also manually link react. See https://github.com/facebook/react/issues/14257.
 
 ## Use Verdaccio
 
 Verdaccio is a good local npm server that you can use to test your packages.
 
-### Install verdaccio
-
-```bash
-npm install --global verdaccio
-```
-
-### Publish to verdaccio
-
-When you are ready to test the code that could make up the next version of your package, you can publish locally to verdaccio
-
-Run verdaccio in a **separate terminal window**:
-
-```bash
-verdaccio
-```
-
-In another terminal window, get ready to publish your local npm package:
-
-```bash
-# Your clone of Docusaurus
-cd /path/to/docusaurus/
-
-# use anything for user, password, email
-# You should only have to do this once as long as you keep verdaccio installed
-npm adduser --registry http://localhost:4873
-
-npm publish --registry http://localhost:4873
-```
-
-You can navigate to localhost:4873 and you can see that your package was published. You can also see it showing you the steps you ran above as well.
-
-### Install the local npm package and test
-
-Now install the package in the repo you want to test Docusaurus on.
+We have a script `test:build:website` that starts a docker with verdaccio, publishes the packages, and initializes a new website in the parent directory. Alternatively, to install a package in the existing project, after you have started the verdaccio service, run
 
 ```bash
-cd /path/to/testing_project/
-mkdir website # if this does not exist already
-cd website
+npm_config_registry="http://localhost:4873" yarn install @docusaurus/core@"2.0.0-beta.8.NEW" # The version should be the latest
 ```
 
-If you do not have a `package.json` file in the `website` directory, create one with the following content:
-
-```json
-{
-  "scripts": {
-    "start": "docusaurus-start",
-    "build": "docusaurus-build",
-    "publish-gh-pages": "docusaurus-publish",
-    "examples": "docusaurus-examples"
-  }
-}
-```
+You can refer to [the implementation](./scripts/test-release.sh) for more details.
 
-Then:
+If you don't have docker, you can still invoke the CLI manually to start the service.
 
 ```bash
-npm install docusaurus --registry http://localhost:4873 # this may be slower than the normal npm registry
-npm run examples # or whatever you want to test, if anything
-npm run start
+npx verdaccio --listen 4873 --config admin/verdaccio.yaml
 ```

admin/testing-changes-on-Docusaurus-itself.md

@@ -8,13 +8,11 @@ It is straightforward to test your Docusaurus changes with Docusaurus.
 
 ```bash
 cd /path/to/docusaurus-repo
-npm install
+yarn install
 cd website
-npm run start
+yarn start
 ```
 
-> If you look in the `website/package.json` file, you will notice that running `start` with `npm run` actually executes the local `start-server.js` file. This is how you know you are running with local code.
-
 ## Debugging Locally
 
 ### VS Code
@@ -43,4 +41,4 @@ Feel free to contribute debug instructions for other IDEs
 
 ### Observing changes
 
-Now that the server is running, you can make changes to the core Docusaurus code and docs to see the effects on the Docusaurus site. LiveReload will reflect changes to the local site in your browser, usually running at http://localhost:3000.
+Note that since most packages are built with TypeScript, you would need to compile them every time to see the effect. Alternatively, you can run `yarn watch` inside the package directory to start an incremental build. Now that the server is running, you can make changes to the core Docusaurus code and docs to see the effects on the Docusaurus site. LiveReload will reflect changes to the local site in your browser, usually running at http://localhost:3000.