This is an automated email from the ASF dual-hosted git repository.
arp pushed a commit to branch HDDS-9225-website-v2
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/HDDS-9225-website-v2 by this
push:
new 1913764c HDDS-10222. Add pnpm guide to contributing guide. (#64)
1913764c is described below
commit 1913764c70fb6250e804ebf146273455ceef1527
Author: Ethan Rose <[email protected]>
AuthorDate: Wed Feb 14 13:41:23 2024 -0800
HDDS-10222. Add pnpm guide to contributing guide. (#64)
---
CONTRIBUTING.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 56 insertions(+), 2 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d3854172..275f1241 100644
--- a/CONTRIBUTING.md
+++ b/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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
