devabhishekpal commented on code in PR #64: URL: https://github.com/apache/ozone-site/pull/64#discussion_r1488548111
########## 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 packages after cloning the repo**: `pnpm install` + + - This will install the exact package versions listed in *pnpm-lock.yaml*. + + - 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* + - The 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. Review Comment: Thanks for clarifying. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
