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

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

Merged
merged 3 commits into from
Feb 14, 2024
Merged

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

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aca5560
Add pnpm guide to contributing
errose28 Jan 26, 2024
f63d1c0
Fixes after reviewing rendered version
errose28 Jan 26, 2024
cf315c2
Update pnpm install explanation
errose28 Feb 13, 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
58 changes: 56 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Copy link

Choose a reason for hiding this comment

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

We can also add command aliases, metadata etc.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

What do you mean by this?

Copy link

Choose a reason for hiding this comment

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

So package.json can have different information other than just the dependencies. For ex in the current website package.json we see various metadata like:

Also it has a scripts section which specifies the exact command to run for the given aliases. For example pnpm start will run docusaurus start.

The package manager essentially checks this scripts section and then treats these as the equivalent of aliases for a command.
This feature is helpful when you want a long command to run, say as a part of some CI build, or to ease the dev process, you can add a new command and reference the actual command you want to run - then you can call it as pnpm <new command name>

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think this is outside the scope of what I was aiming to cover. Basically I wanted to add just enough info that people could confidently do package updates with just this guide since most are probably not familiar with pnpm. That's why I put this sentence at the beginning:

Basic knowledge required to maintain the website's dependencies is outlined here. See pnpm docs for complete usage.

- **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*.
errose28 marked this conversation as resolved.
Show resolved Hide resolved

- 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.
errose28 marked this conversation as resolved.
Show resolved Hide resolved

- 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)

Expand All @@ -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.

Expand Down Expand Up @@ -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.