HDDS-10222. Add pnpm guide to contributing guide. (#64)

CONTRIBUTING.md

@@ -190,11 +190,63 @@ Changing appearance or theme of the website from Docusaurus defaults can be done
 
 - Make sure styling changes work in both [light and dark modes](https://docusaurus.io/docs/styling-layout#dark-mode).
 
+### Package Management
+
+The website uses [pnpm](https://pnpm.io/) as a package manager. This is the same package manager used to build [Recon](https://github.com/apache/ozone/tree/master/hadoop-ozone/recon/src/main/resources/webapps/recon/ozone-recon-web). Basic knowledge required to maintain the website's dependencies is outlined here. See [pnpm docs](https://pnpm.io/pnpm-cli) for complete usage.
+
+#### Relevant Files
+
+- **package.json**
+
+This file contains version guidelines for all the top level dependencies required to build the website. This file may be updated manually to adjust which versions are installed, or automatically when commands like `pnpm update` are run.
+
+- **pnpm-lock.yaml**
+
+This file contains exact version information of all dependencies required to build the website. These are the versions of packages that will be used when `pnpm install` is run. This file should not be updated manually, and may be updated automatically by commands like `pnpm update`.
+
+#### Version Pinning
+
+*package.json* allows [version specifiers](https://docs.npmjs.com/about-semantic-versioning#using-semantic-versioning-to-specify-update-types-your-package-can-accept) to put limits on which versions are installed. The following specifiers are currently used for the website:
+- `~` means to allow all patch updates (last semantic versioning digit)
+- `^` means to allow all minor version updates (second semantic versioning digit)
+- A version with no specifier means only the exact version declared in *package.json* is allowed.
+
+Currently all `@docusaurus/*` packages are pinned to an exact version for website stability.
+
+#### Command Cheat-Sheet
+
+- **To install all packages after cloning the repo**: `pnpm install`
+
+  - This will read the metadata for the packages and their transitive dependencies from *pnpm-lock.yaml*, which is generated from *package.json* - and install the required dependencies for the project in the *node_modules* folder.
+
+  - This should make no modifications to *package.json* or *pnpm-lock.yaml* if all explicit versions in *pnpm-lock.yaml* comply with the version specifiers in *package.json*.
+
+    - This should always be true for committed code, because the CI build of the website uses `pnpm install --frozen-lockfile` to fail the build if the two files do not match.
+
+- **To update all packages to their latest versions allowed by package.json**: `pnpm update`
+
+    - This will update *package.json* to match the exact versions that were installed, but this is for reference only. Exact version information still comes from *pnpm-lock.yaml*
+      - Version specifiers like `^` and `~` will not be modified, and the new version will be the latest that still complies with the existing version specifiers.
+
+    - This will update *pnpm-lock.yaml* to reflect the exact versions of all top level and transitive dependencies installed.
+
+- **To update docusaurus to a specific version**:
+
+  1. Update the version of all `@docusaurus/*` packages in *package.json* to the desired docusaurus version.
+
+  2. Run `pnpm update '@docusaurus/*'` to update to the new version.
+
+    - This should modify *pnpm-lock.yaml* with the exact versions of docusaurus and its transitive dependencies that were installed.
+
+    - If pnpm needed to update other top level dependencies when updating docusaurus, this command may modify *package.json* as well.
+
+  3. Commit *package.json* and *pnpm-lock.yaml* to git.
+
 ### Previewing Your Modifications Locally
 
 Docusaurus supports previewing the website locally. Below are various options to launch a preview of the site at `localhost:3000` on your machine.
 
-**NOTE** If using the [Docusaurus development server](https://docusaurus.io/docs/installation#running-the-development-server), changes to `docusaurus.config.js` may not be automatically reloaded and require the server to be restarted.
+**NOTE**: If using the [Docusaurus development server](https://docusaurus.io/docs/installation#running-the-development-server), changes to `docusaurus.config.js` may not be automatically reloaded and require the server to be restarted.
 
 #### Option 1: Docker (Recommended)
 
@@ -205,6 +257,8 @@ The project includes a `Dockerfile` and a `compose.yml` file to build and run th
 2. Install [docker compose](https://docs.docker.com/compose/install/).
 
 3. Run `docker compose up` from the repository root.
+  - **Note**: This will continue to use the last locally built version of the `ozone-site-dev` image, which saves time on future runs.
+    - Run `docker compose up --build` to rebuild the image and incorporate any package dependency updates that may have been committed since the last build.
 
 4. Preview the website at `localhost:3000` in your browser.
 
@@ -240,4 +294,4 @@ Build and run the website locally with the `pnpm` package manager.
 
 ### Contributing Your Modifications
 
-Fork the [apache/ozone-site](https://github.com/apache/ozone-site) repo and follow the same steps as the main [Ozone contributing guide](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md#contribute-your-modifications) to create a pull request against the [apache/ozone-site](https://github.com/apache/ozone-site) repository. the target branch for the PR should be `HDDS-9225-website-v2` for changes targeting this new unreleased version of the website.
+Fork the [apache/ozone-site](https://github.com/apache/ozone-site) repo and follow the same steps as the main [Ozone contributing guide](https://github.com/apache/ozone/blob/master/CONTRIBUTING.md#contribute-your-modifications) to create a pull request against the [apache/ozone-site](https://github.com/apache/ozone-site) repository. The target branch for the PR should be `HDDS-9225-website-v2` for changes targeting this new unreleased version of the website.