jojochuang commented on code in PR #541: URL: https://github.com/apache/ozone-site/pull/541#discussion_r4139326702
########## 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`. Review Comment: - If you added or changed Markdown or MDX content, or added or renamed files under `docs/` or `src/pages/`, run `.github/scripts/spelling.sh`. -- 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]
