From 8fe9a5083670cc37c64c8165998ea71e33035e57 Mon Sep 17 00:00:00 2001 From: Mark Tsai Date: Tue, 25 Aug 2026 22:48:13 +0800 Subject: [PATCH 1/2] HDDS-15790. Add AGENTS.md and CLAUDE.md Co-Authored-By: Claude Code --- AGENTS.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 152 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..3e6e703dc9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,151 @@ +# AGENTS instructions + +## Working Style + +- Prefer the smallest correct change. Do not add features, refactors, or + cleanup that were not asked for. +- Keep diffs surgical. Every changed line should trace back to the task. + Do not reformat, rewrap, or rename adjacent pages "while you are here". +- Match the surrounding page or module before introducing a new pattern. +- If there are multiple reasonable interpretations, state the tradeoff and + ask instead of guessing. +- Use established Ozone vocabulary in docs and PR text: + SCM, OM, Datanode, container, pipeline, volume, bucket, key, snapshot, + Recon, FSO, OBS, and S3 Gateway. + Avoid inventing new architecture terms unless the repo already uses them. + +## Repository Snapshot + +This repository is the Apache Ozone website +([ozone.apache.org](https://ozone.apache.org/)), built with Docusaurus. +It is not the Ozone storage system. Product code lives in +[`apache/ozone`](https://github.com/apache/ozone). + +Package coordinates (Node engine, pnpm version, Docusaurus version) live in +[`package.json`](./package.json). Do not hardcode those versions in new docs. + +Two branches: + +- `master`: source. All website PRs target this branch. +- `asf-site`: build output. CI publishes here. Do not edit it by hand. + +## Local Environment + +- Docker Compose is the recommended preview path and does not require pnpm. +- For lint and local `pnpm` commands, enable Corepack and use the Node + version that CI uses (see `Dockerfile` and `.github/workflows/static.yml`). +- Preview and serve listen on port 3001, not the Docusaurus default 3000. +- After changing `docusaurus.config.js`, restart the dev server. + Hot reload may not pick up config edits. + +## Commands + +Primary commands (see `package.json` for the full script list): + +- Preview with Docker: `docker compose up` + then open `http://localhost:3001` +- Preview with pnpm: `pnpm install` then `pnpm start` +- Production build: `pnpm build` +- Serve the build: `pnpm serve` +- Lint: `pnpm run lint` +- Auto-fix lint: `pnpm run lint:fix` +- Spell check: `.github/scripts/spelling.sh` +- CI-aligned website build: `docker compose run site pnpm build` + +Notes: + +- `pnpm run lint` needs `yamllint` on `PATH` + (`pip install yamllint` or `brew install yamllint`). +- The Docker image installs `--prod` dependencies only. Do not rely on + `docker compose run site pnpm run lint` for eslint or markdownlint. +- Rebuild the image after dependency changes: `docker compose up --build` + +## Repository Structure + +- `src/pages/`: standalone pages (home, download, Community). No docs + sidebar and no versioning. +- `docs/`: product docs for the Next version. Number-prefixed paths. +- `versioned_docs/`: snapshots of released docs. Do not update unless the + task is an explicit backport. +- `blog/`: blog posts. +- `static/`: copied as-is into the site root. +- `src/theme/`: swizzled Docusaurus components. +- `docusaurus.config.js`: site config, navbar, footer. +- `.github/`: CI workflows and check scripts. + +## Change Boundaries + +- Keep page types separated. Community and download content belongs in + `src/pages/`. Product documentation belongs in `docs/`. +- Do not edit the `asf-site` branch. +- Do not update `versioned_docs/` unless the change is an explicit + backport to a released version. Default to `docs/` (Next) only. +- Do not hand-edit generated configuration appendix pages when a + generation workflow exists. +- Do not enable a `docs.exclude` section, navbar item, or plugin just + because a draft page exists. +- Do not rearrange sidebar order or rename files for cosmetics. + +## Coding Standards + +- Follow the surrounding Markdown and JavaScript. Lint config is + `.markdownlint.yaml` and `eslint.config.mjs`. +- Use ATX headings (`#`) and dash (`-`) lists. +- Keep headings at or under 80 characters. +- Add the Apache license header to new source files (`.js`, `.yml`, + and similar). Markdown and MDX under this repo are exempted by + `.licenserc.yaml`. +- Do not add `@author` tags. +- Keep comments concrete. Avoid vague architecture prose. + +## Testing Standards + +- Preview the affected URL at `http://localhost:3001` when the change + is a page or style. +- Run `pnpm run lint` before opening a PR. +- Run `pnpm build`. Broken links, anchors, and duplicate routes fail + the build (`onBrokenLinks` / `onBrokenAnchors` in + `docusaurus.config.js`). +- If you added files, run `.github/scripts/spelling.sh`. +- Root files such as this `AGENTS.md` are not website routes. Do not + treat "no new URL" as a test failure. + +## Commits and PRs + +- Every change should map to an Apache Jira in the HDDS project. + Website issues may also use the `website` and `documentation` labels. +- Branch names usually start with the Jira ID, for example `HDDS-1234`. +- PR titles must be `HDDS-1234. Short summary of the change`. +- Prefer commit subjects that also start with the Jira ID when known. +- To bring a branch up to date with `master`, merge instead of rebasing: + `git merge --no-edit origin/master` +- Avoid force-push unless a maintainer explicitly asks for rewritten + history. +- PR descriptions should include the Jira link, the problem statement, + the chosen approach, and how the patch was tested. +- When non-trivial content is generated with AI tooling, disclose it in + the PR description as `Generated-by: TOOL (MODEL)`. + See the ASF generative tooling guidance. + +## Ask First + +- New third-party dependencies or Docusaurus plugins +- Navbar, footer, or other `docusaurus.config.js` structure changes +- Publishing a previously excluded docs section +- Backports into `versioned_docs/` +- Broad terminology or heading cleanups across many files + +## Never + +- Commit secrets, credentials, or tokens +- Use destructive git commands unless explicitly requested +- Hand-edit `asf-site` or generated web artifacts +- Add unrelated cleanup, formatting churn, or speculative refactors + to the same change + +## References + +- [`CONTRIBUTING.md`](./CONTRIBUTING.md) +- [`.github/pull_request_template.md`](./.github/pull_request_template.md) +- [Docusaurus docs](https://docusaurus.io/docs) +- [ASF generative tooling guidance](https://www.apache.org/legal/generative-tooling.html) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 9d45c21014df9df625fffad05c3ead6495341659 Mon Sep 17 00:00:00 2001 From: Mark Tsai Date: Tue, 25 Aug 2026 23:16:14 +0800 Subject: [PATCH 2/2] HDDS-15790. Add ATX to cspell word list --- cspell.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/cspell.yaml b/cspell.yaml index efbcf2de02..80450d286f 100644 --- a/cspell.yaml +++ b/cspell.yaml @@ -237,6 +237,7 @@ words: - Ints - jre # Misc words +- ATX - acking - ACK - dashboarding