You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@ozone.apache.org by "smengcl (via GitHub)" <gi...@apache.org> on 2026/05/18 22:27:07 UTC
[PR] HDDS-15316. Add CLAUDE.md [ozone]
smengcl opened a new pull request, #10302:
URL: https://github.com/apache/ozone/pull/10302
Generated-by: Claude Code w/ Opus 4.7
## What changes were proposed in this pull request?
Init CLAUDE.md for ozone.
This can be considered a subtask of [HDDS-15158](https://issues.apache.org/jira/browse/HDDS-15158)
This is generated using `/init` command in Claude Code. Using Opus 4.7 xhigh.
Added checkstyle CI workflow in addition to the originally generated content.
## What is the link to the Apache JIRA
https://issues.apache.org/jira/browse/HDDS-15316
## How was this patch tested?
- n/a
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3263142340
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository
+
+Apache Ozone — a scalable, distributed object/file store. This is a multi-module Maven project; root coordinates and current version are in [`pom.xml`](./pom.xml) (`groupId` / `artifactId` / `version`). Two top-level Maven aggregators:
+
+- `hadoop-hdds/` — Hadoop Distributed Data Store: the storage layer (SCM, datanode container service, RocksDB integration, common protocols, crypto, framework). Load-bearing submodules: `server-scm`, `container-service`, `framework`, `managed-rocksdb`, `interface-{admin,client,server}`. See `hadoop-hdds/pom.xml` for the full list.
+- `hadoop-ozone/` — Ozone services and clients on top of HDDS. Load-bearing submodules: `ozone-manager` (OM), `s3gateway`, `recon` (UI/monitoring), `datanode`, `dist` (binary tarball + Docker compose configs), `integration-test*` (Java mini-cluster tests), plus `ozonefs*` (Hadoop-compatible FS adapters). See `hadoop-ozone/pom.xml` for the full list.
+
+The big-picture component split: SCM manages containers/pipelines, OM manages namespace/keys, datanodes serve container data via Ratis (RAFT), Recon provides observability, and S3 Gateway / OzoneFS expose S3 and Hadoop FS APIs. Module boundaries follow this split — when changing a feature, expect edits across `hadoop-hdds/interface-*` (proto), an HDDS server module, and one of `ozone-manager` / `s3gateway` / `recon`. Integration tests for these flows live exclusively in `hadoop-ozone/integration-test*`.
Review Comment:
We can add the tech stack for Ozone such as Java version (Java 8 with JDK21 compatibility), build systems (maven), communication protocol (Hadoop RPC & gRPC on protobuf), testing library (JUnit 5).
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Review Comment:
Remove this specific Claude-specific instruction
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository
+
+Apache Ozone — a scalable, distributed object/file store. This is a multi-module Maven project; root coordinates and current version are in [`pom.xml`](./pom.xml) (`groupId` / `artifactId` / `version`). Two top-level Maven aggregators:
+
+- `hadoop-hdds/` — Hadoop Distributed Data Store: the storage layer (SCM, datanode container service, RocksDB integration, common protocols, crypto, framework). Load-bearing submodules: `server-scm`, `container-service`, `framework`, `managed-rocksdb`, `interface-{admin,client,server}`. See `hadoop-hdds/pom.xml` for the full list.
+- `hadoop-ozone/` — Ozone services and clients on top of HDDS. Load-bearing submodules: `ozone-manager` (OM), `s3gateway`, `recon` (UI/monitoring), `datanode`, `dist` (binary tarball + Docker compose configs), `integration-test*` (Java mini-cluster tests), plus `ozonefs*` (Hadoop-compatible FS adapters). See `hadoop-ozone/pom.xml` for the full list.
+
+The big-picture component split: SCM manages containers/pipelines, OM manages namespace/keys, datanodes serve container data via Ratis (RAFT), Recon provides observability, and S3 Gateway / OzoneFS expose S3 and Hadoop FS APIs. Module boundaries follow this split — when changing a feature, expect edits across `hadoop-hdds/interface-*` (proto), an HDDS server module, and one of `ozone-manager` / `s3gateway` / `recon`. Integration tests for these flows live exclusively in `hadoop-ozone/integration-test*`.
+
+## Build
+
+```bash
+mvn clean install -DskipTests # build + install to local repo (use this when iterating across modules; required before single-module rebuilds resolve correctly)
+mvn clean verify -DskipTests # end-to-end compile/verify without installing — useful as a smoke check, not for iterative dev
+```
+
+Useful flags (composable):
+- `-DskipShade` — skip building the shaded Ozone FS jar (saves time; omit this flag if you need to run filesystem integration tests, which require the shaded jar)
+- `-DskipRecon` — skip Recon Web UI (~2 min faster)
+- `-DskipDocs` — skip Hugo docs build
+- `-Pdist` — build the binary tarball under `hadoop-ozone/dist/target/`
Review Comment:
We can prompt the model to use this when building locally.
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
Review Comment:
Let's create a AGENTS.md instead and make CLAUDE.md symlink to it. See https://github.com/apache/airflow
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3270705555
##########
AGENTS.md:
##########
@@ -0,0 +1,80 @@
+# AGENTS.md
Review Comment:
I think we can avoid things that have not been standardized yet (e.g. AGENTS.md). Or we can address it in the future in a separate directory.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3270705555
##########
AGENTS.md:
##########
@@ -0,0 +1,80 @@
+# AGENTS.md
Review Comment:
Yes, but I think we can address this in the future. I would prefer if we develop our own Ozone-related skills (e.g. Cassandra bug hunting skills https://github.com/apache/cassandra/pull/4794) instead of using the generic skills like https://github.com/obra/superpowers
And for skills, let's standardize to something like https://agentskills.io instead of Cursor specific formats.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "smengcl (via GitHub)" <gi...@apache.org>.
smengcl commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3383214643
##########
AGENTS.md:
##########
@@ -0,0 +1,80 @@
+# AGENTS.md
Review Comment:
@yandrey321 Do you want to file a jira for skills to be added?
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3263187898
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository
+
+Apache Ozone — a scalable, distributed object/file store. This is a multi-module Maven project; root coordinates and current version are in [`pom.xml`](./pom.xml) (`groupId` / `artifactId` / `version`). Two top-level Maven aggregators:
+
+- `hadoop-hdds/` — Hadoop Distributed Data Store: the storage layer (SCM, datanode container service, RocksDB integration, common protocols, crypto, framework). Load-bearing submodules: `server-scm`, `container-service`, `framework`, `managed-rocksdb`, `interface-{admin,client,server}`. See `hadoop-hdds/pom.xml` for the full list.
+- `hadoop-ozone/` — Ozone services and clients on top of HDDS. Load-bearing submodules: `ozone-manager` (OM), `s3gateway`, `recon` (UI/monitoring), `datanode`, `dist` (binary tarball + Docker compose configs), `integration-test*` (Java mini-cluster tests), plus `ozonefs*` (Hadoop-compatible FS adapters). See `hadoop-ozone/pom.xml` for the full list.
+
+The big-picture component split: SCM manages containers/pipelines, OM manages namespace/keys, datanodes serve container data via Ratis (RAFT), Recon provides observability, and S3 Gateway / OzoneFS expose S3 and Hadoop FS APIs. Module boundaries follow this split — when changing a feature, expect edits across `hadoop-hdds/interface-*` (proto), an HDDS server module, and one of `ozone-manager` / `s3gateway` / `recon`. Integration tests for these flows live exclusively in `hadoop-ozone/integration-test*`.
+
+## Build
+
+```bash
+mvn clean install -DskipTests # build + install to local repo (use this when iterating across modules; required before single-module rebuilds resolve correctly)
+mvn clean verify -DskipTests # end-to-end compile/verify without installing — useful as a smoke check, not for iterative dev
+```
+
+Useful flags (composable):
+- `-DskipShade` — skip building the shaded Ozone FS jar (saves time; omit this flag if you need to run filesystem integration tests, which require the shaded jar)
+- `-DskipRecon` — skip Recon Web UI (~2 min faster)
+- `-DskipDocs` — skip Hugo docs build
+- `-Pdist` — build the binary tarball under `hadoop-ozone/dist/target/`
+
+Single-module rebuild after a change (note the leading colon for the artifactId):
+```bash
+mvn -pl :ozone-manager -am install -DskipTests
+```
+
+## Running tests
+
+`hadoop-ozone/dev-support/checks/` contains the same scripts CI runs. Each writes results to `target/<check-name>/` (or `$OUTPUT_DIR`) and exits non-zero on failure. Most useful locally:
+
+- `unit.sh` — pure unit tests (excludes the `ozone-integration-test*` and `mini-chaos-tests` modules)
+- `integration.sh` — Java mini-cluster integration tests (slow)
+- `checkstyle.sh`, `pmd.sh`, `findbugs.sh`, `rat.sh`, `author.sh` — static checks
+- `acceptance.sh` — robot-framework smoketests against a real docker-compose cluster (requires `docker`, `docker-compose`, `jq`)
+- `kubernetes.sh` — limited k8s test suite
+
+Direct Maven equivalents (for running a single test):
+```bash
+# Single test class
+mvn -pl :ozone-manager test -Dtest=TestOzoneManagerLock
+# Single test method
+mvn -pl :ozone-manager test -Dtest=TestOzoneManagerLock#testLockingOrder
+# Integration tests live in their own modules and require -DskipShade etc.
+mvn -pl :ozone-integration-test test -Dtest=TestOmContainerLocationCache -DskipShade -DskipRecon
+```
+
+Re-run flaky tests with the `test-flaky` profile (CI does this): `integration.sh -Ptest-flaky` adds `-Dsurefire.rerunFailingTestsCount=5`.
+
+`build.sh` honors `FAIL_FAST=true`, `ITERATIONS=N`, and `OZONE_WITH_COVERAGE=true` env vars; pass extra Maven args after the script name.
+
+## Running a local cluster
+
+After a `-Pdist` build:
+```bash
+cd hadoop-ozone/dist/target/ozone-*-SNAPSHOT/compose/ozone
+OZONE_REPLICATION_FACTOR=3 ./run.sh -d
+```
+`hadoop-ozone/dist/src/main/compose/` has many topologies (`ozone-ha`, `ozonesecure`, `upgrade`, `xcompat`, etc.). For IDE-launched components there are pre-baked IntelliJ run configs in `.run/`; the documented startup order is SCM init → SCM → OM init → OM → Recon → datanodes.
+
+## Conventions and PR workflow
+
+The authoritative source is [`CONTRIBUTING.md`](./CONTRIBUTING.md). Highlights worth surfacing here:
+
+- PR titles start with the Jira id (e.g. `HDDS-12345. Short description`); every change needs an `HDDS-NNNN` Jira.
+- Update branches via `git merge --no-edit origin/master`, **not** rebase; avoid force-push.
+- 2-space indent, 120-char lines, Apache license header on most files (enforced by Checkstyle and RAT — Markdown excludes are managed in `dev-support/rat/rat-exclusions.txt`); no `@author` tags. Checkstyle config: `hadoop-hdds/dev-support/checkstyle/checkstyle.xml`.
+- For non-trivial features, follow the OEP (Ozone Enhancement Proposal) process — design docs in Markdown.
+- Before wrapping up a change (e.g. before posting a PR), run `./hadoop-ozone/dev-support/checks/checkstyle.sh` locally to catch violations — otherwise the checkstyle CI job will fail immediately on the PR. `rat.sh` is also worth running if you've added new file types.
Review Comment:
Also add the "Generated by: "TOOL" ("MODEL") based on the https://www.apache.org/legal/generative-tooling.html (e.g. "Generated by: Codex (GPT 5.5))
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository
+
+Apache Ozone — a scalable, distributed object/file store. This is a multi-module Maven project; root coordinates and current version are in [`pom.xml`](./pom.xml) (`groupId` / `artifactId` / `version`). Two top-level Maven aggregators:
+
+- `hadoop-hdds/` — Hadoop Distributed Data Store: the storage layer (SCM, datanode container service, RocksDB integration, common protocols, crypto, framework). Load-bearing submodules: `server-scm`, `container-service`, `framework`, `managed-rocksdb`, `interface-{admin,client,server}`. See `hadoop-hdds/pom.xml` for the full list.
+- `hadoop-ozone/` — Ozone services and clients on top of HDDS. Load-bearing submodules: `ozone-manager` (OM), `s3gateway`, `recon` (UI/monitoring), `datanode`, `dist` (binary tarball + Docker compose configs), `integration-test*` (Java mini-cluster tests), plus `ozonefs*` (Hadoop-compatible FS adapters). See `hadoop-ozone/pom.xml` for the full list.
+
+The big-picture component split: SCM manages containers/pipelines, OM manages namespace/keys, datanodes serve container data via Ratis (RAFT), Recon provides observability, and S3 Gateway / OzoneFS expose S3 and Hadoop FS APIs. Module boundaries follow this split — when changing a feature, expect edits across `hadoop-hdds/interface-*` (proto), an HDDS server module, and one of `ozone-manager` / `s3gateway` / `recon`. Integration tests for these flows live exclusively in `hadoop-ozone/integration-test*`.
+
+## Build
+
+```bash
+mvn clean install -DskipTests # build + install to local repo (use this when iterating across modules; required before single-module rebuilds resolve correctly)
+mvn clean verify -DskipTests # end-to-end compile/verify without installing — useful as a smoke check, not for iterative dev
+```
+
+Useful flags (composable):
+- `-DskipShade` — skip building the shaded Ozone FS jar (saves time; omit this flag if you need to run filesystem integration tests, which require the shaded jar)
+- `-DskipRecon` — skip Recon Web UI (~2 min faster)
+- `-DskipDocs` — skip Hugo docs build
+- `-Pdist` — build the binary tarball under `hadoop-ozone/dist/target/`
+
+Single-module rebuild after a change (note the leading colon for the artifactId):
+```bash
+mvn -pl :ozone-manager -am install -DskipTests
+```
+
+## Running tests
+
+`hadoop-ozone/dev-support/checks/` contains the same scripts CI runs. Each writes results to `target/<check-name>/` (or `$OUTPUT_DIR`) and exits non-zero on failure. Most useful locally:
+
+- `unit.sh` — pure unit tests (excludes the `ozone-integration-test*` and `mini-chaos-tests` modules)
+- `integration.sh` — Java mini-cluster integration tests (slow)
+- `checkstyle.sh`, `pmd.sh`, `findbugs.sh`, `rat.sh`, `author.sh` — static checks
+- `acceptance.sh` — robot-framework smoketests against a real docker-compose cluster (requires `docker`, `docker-compose`, `jq`)
+- `kubernetes.sh` — limited k8s test suite
+
+Direct Maven equivalents (for running a single test):
+```bash
+# Single test class
+mvn -pl :ozone-manager test -Dtest=TestOzoneManagerLock
+# Single test method
+mvn -pl :ozone-manager test -Dtest=TestOzoneManagerLock#testLockingOrder
+# Integration tests live in their own modules and require -DskipShade etc.
+mvn -pl :ozone-integration-test test -Dtest=TestOmContainerLocationCache -DskipShade -DskipRecon
+```
+
+Re-run flaky tests with the `test-flaky` profile (CI does this): `integration.sh -Ptest-flaky` adds `-Dsurefire.rerunFailingTestsCount=5`.
+
+`build.sh` honors `FAIL_FAST=true`, `ITERATIONS=N`, and `OZONE_WITH_COVERAGE=true` env vars; pass extra Maven args after the script name.
+
+## Running a local cluster
+
+After a `-Pdist` build:
+```bash
+cd hadoop-ozone/dist/target/ozone-*-SNAPSHOT/compose/ozone
+OZONE_REPLICATION_FACTOR=3 ./run.sh -d
+```
+`hadoop-ozone/dist/src/main/compose/` has many topologies (`ozone-ha`, `ozonesecure`, `upgrade`, `xcompat`, etc.). For IDE-launched components there are pre-baked IntelliJ run configs in `.run/`; the documented startup order is SCM init → SCM → OM init → OM → Recon → datanodes.
+
+## Conventions and PR workflow
+
+The authoritative source is [`CONTRIBUTING.md`](./CONTRIBUTING.md). Highlights worth surfacing here:
+
+- PR titles start with the Jira id (e.g. `HDDS-12345. Short description`); every change needs an `HDDS-NNNN` Jira.
+- Update branches via `git merge --no-edit origin/master`, **not** rebase; avoid force-push.
+- 2-space indent, 120-char lines, Apache license header on most files (enforced by Checkstyle and RAT — Markdown excludes are managed in `dev-support/rat/rat-exclusions.txt`); no `@author` tags. Checkstyle config: `hadoop-hdds/dev-support/checkstyle/checkstyle.xml`.
+- For non-trivial features, follow the OEP (Ozone Enhancement Proposal) process — design docs in Markdown.
+- Before wrapping up a change (e.g. before posting a PR), run `./hadoop-ozone/dev-support/checks/checkstyle.sh` locally to catch violations — otherwise the checkstyle CI job will fail immediately on the PR. `rat.sh` is also worth running if you've added new file types.
Review Comment:
Also add the "Generated by: "TOOL" ("MODEL") based on the https://www.apache.org/legal/generative-tooling.html (e.g. "Generated by: Codex (GPT 5.5)")
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "yandrey321 (via GitHub)" <gi...@apache.org>.
yandrey321 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3269250798
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository
+
+Apache Ozone — a scalable, distributed object/file store. This is a multi-module Maven project; root coordinates and current version are in [`pom.xml`](./pom.xml) (`groupId` / `artifactId` / `version`). Two top-level Maven aggregators:
+
+- `hadoop-hdds/` — Hadoop Distributed Data Store: the storage layer (SCM, datanode container service, RocksDB integration, common protocols, crypto, framework). Load-bearing submodules: `server-scm`, `container-service`, `framework`, `managed-rocksdb`, `interface-{admin,client,server}`. See `hadoop-hdds/pom.xml` for the full list.
+- `hadoop-ozone/` — Ozone services and clients on top of HDDS. Load-bearing submodules: `ozone-manager` (OM), `s3gateway`, `recon` (UI/monitoring), `datanode`, `dist` (binary tarball + Docker compose configs), `integration-test*` (Java mini-cluster tests), plus `ozonefs*` (Hadoop-compatible FS adapters). See `hadoop-ozone/pom.xml` for the full list.
+
+The big-picture component split: SCM manages containers/pipelines, OM manages namespace/keys, datanodes serve container data via Ratis (RAFT), Recon provides observability, and S3 Gateway / OzoneFS expose S3 and Hadoop FS APIs. Module boundaries follow this split — when changing a feature, expect edits across `hadoop-hdds/interface-*` (proto), an HDDS server module, and one of `ozone-manager` / `s3gateway` / `recon`. Integration tests for these flows live exclusively in `hadoop-ozone/integration-test*`.
+
+## Build
+
+```bash
+mvn clean install -DskipTests # build + install to local repo (use this when iterating across modules; required before single-module rebuilds resolve correctly)
+mvn clean verify -DskipTests # end-to-end compile/verify without installing — useful as a smoke check, not for iterative dev
+```
+
+Useful flags (composable):
+- `-DskipShade` — skip building the shaded Ozone FS jar (saves time; omit this flag if you need to run filesystem integration tests, which require the shaded jar)
+- `-DskipRecon` — skip Recon Web UI (~2 min faster)
+- `-DskipDocs` — skip Hugo docs build
+- `-Pdist` — build the binary tarball under `hadoop-ozone/dist/target/`
Review Comment:
Agent shall know what commands to execute to validate the changes, optional commands could confuse the agent.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add CLAUDE.md [ozone]
Posted by "smengcl (via GitHub)" <gi...@apache.org>.
smengcl commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3268414363
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository
+
+Apache Ozone — a scalable, distributed object/file store. This is a multi-module Maven project; root coordinates and current version are in [`pom.xml`](./pom.xml) (`groupId` / `artifactId` / `version`). Two top-level Maven aggregators:
+
+- `hadoop-hdds/` — Hadoop Distributed Data Store: the storage layer (SCM, datanode container service, RocksDB integration, common protocols, crypto, framework). Load-bearing submodules: `server-scm`, `container-service`, `framework`, `managed-rocksdb`, `interface-{admin,client,server}`. See `hadoop-hdds/pom.xml` for the full list.
+- `hadoop-ozone/` — Ozone services and clients on top of HDDS. Load-bearing submodules: `ozone-manager` (OM), `s3gateway`, `recon` (UI/monitoring), `datanode`, `dist` (binary tarball + Docker compose configs), `integration-test*` (Java mini-cluster tests), plus `ozonefs*` (Hadoop-compatible FS adapters). See `hadoop-ozone/pom.xml` for the full list.
+
+The big-picture component split: SCM manages containers/pipelines, OM manages namespace/keys, datanodes serve container data via Ratis (RAFT), Recon provides observability, and S3 Gateway / OzoneFS expose S3 and Hadoop FS APIs. Module boundaries follow this split — when changing a feature, expect edits across `hadoop-hdds/interface-*` (proto), an HDDS server module, and one of `ozone-manager` / `s3gateway` / `recon`. Integration tests for these flows live exclusively in `hadoop-ozone/integration-test*`.
+
+## Build
+
+```bash
+mvn clean install -DskipTests # build + install to local repo (use this when iterating across modules; required before single-module rebuilds resolve correctly)
+mvn clean verify -DskipTests # end-to-end compile/verify without installing — useful as a smoke check, not for iterative dev
+```
+
+Useful flags (composable):
+- `-DskipShade` — skip building the shaded Ozone FS jar (saves time; omit this flag if you need to run filesystem integration tests, which require the shaded jar)
+- `-DskipRecon` — skip Recon Web UI (~2 min faster)
+- `-DskipDocs` — skip Hugo docs build
+- `-Pdist` — build the binary tarball under `hadoop-ozone/dist/target/`
+
+Single-module rebuild after a change (note the leading colon for the artifactId):
+```bash
+mvn -pl :ozone-manager -am install -DskipTests
+```
+
+## Running tests
+
+`hadoop-ozone/dev-support/checks/` contains the same scripts CI runs. Each writes results to `target/<check-name>/` (or `$OUTPUT_DIR`) and exits non-zero on failure. Most useful locally:
+
+- `unit.sh` — pure unit tests (excludes the `ozone-integration-test*` and `mini-chaos-tests` modules)
+- `integration.sh` — Java mini-cluster integration tests (slow)
+- `checkstyle.sh`, `pmd.sh`, `findbugs.sh`, `rat.sh`, `author.sh` — static checks
+- `acceptance.sh` — robot-framework smoketests against a real docker-compose cluster (requires `docker`, `docker-compose`, `jq`)
+- `kubernetes.sh` — limited k8s test suite
+
+Direct Maven equivalents (for running a single test):
+```bash
+# Single test class
+mvn -pl :ozone-manager test -Dtest=TestOzoneManagerLock
+# Single test method
+mvn -pl :ozone-manager test -Dtest=TestOzoneManagerLock#testLockingOrder
+# Integration tests live in their own modules and require -DskipShade etc.
+mvn -pl :ozone-integration-test test -Dtest=TestOmContainerLocationCache -DskipShade -DskipRecon
+```
+
+Re-run flaky tests with the `test-flaky` profile (CI does this): `integration.sh -Ptest-flaky` adds `-Dsurefire.rerunFailingTestsCount=5`.
+
+`build.sh` honors `FAIL_FAST=true`, `ITERATIONS=N`, and `OZONE_WITH_COVERAGE=true` env vars; pass extra Maven args after the script name.
+
+## Running a local cluster
+
+After a `-Pdist` build:
+```bash
+cd hadoop-ozone/dist/target/ozone-*-SNAPSHOT/compose/ozone
+OZONE_REPLICATION_FACTOR=3 ./run.sh -d
+```
+`hadoop-ozone/dist/src/main/compose/` has many topologies (`ozone-ha`, `ozonesecure`, `upgrade`, `xcompat`, etc.). For IDE-launched components there are pre-baked IntelliJ run configs in `.run/`; the documented startup order is SCM init → SCM → OM init → OM → Recon → datanodes.
+
+## Conventions and PR workflow
+
+The authoritative source is [`CONTRIBUTING.md`](./CONTRIBUTING.md). Highlights worth surfacing here:
+
+- PR titles start with the Jira id (e.g. `HDDS-12345. Short description`); every change needs an `HDDS-NNNN` Jira.
+- Update branches via `git merge --no-edit origin/master`, **not** rebase; avoid force-push.
+- 2-space indent, 120-char lines, Apache license header on most files (enforced by Checkstyle and RAT — Markdown excludes are managed in `dev-support/rat/rat-exclusions.txt`); no `@author` tags. Checkstyle config: `hadoop-hdds/dev-support/checkstyle/checkstyle.xml`.
+- For non-trivial features, follow the OEP (Ozone Enhancement Proposal) process — design docs in Markdown.
+- Before wrapping up a change (e.g. before posting a PR), run `./hadoop-ozone/dev-support/checks/checkstyle.sh` locally to catch violations — otherwise the checkstyle CI job will fail immediately on the PR. `rat.sh` is also worth running if you've added new file types.
Review Comment:
good point. done
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "smengcl (via GitHub)" <gi...@apache.org>.
smengcl commented on PR #10302:
URL: https://github.com/apache/ozone/pull/10302#issuecomment-4663219672
> > This is generated using /init command in Claude Code. Using Opus 4.7 xhigh.
>
> I think using the AGENTS.md using Claude Code /init is not advisable. See [humanlayer.dev/blog/writing-a-good-claude-md](https://www.humanlayer.dev/blog/writing-a-good-claude-md) for the reasoning.
>
> Since AGENTS.md will be loaded for each session, it is important we get this right (otherwise it might be a regression). I would prefer if the creator can try using the AGENTS.md for a while (to do bug fixes, creating small to large features) and update based on their findings and shortcomings. This would increase the community confidence in these AGENTS.md
>
> Personally, these are the things I would add:
>
> * Prefer merging new integration tests with existing integration tests (i.e. avoid creating a new MiniOzoneCluster for every test).
> * Prefer to use Ratis utilites (e.g. Ratis Preconditions, etc) and reuse existing functions
> * No unnecessary line-wrap (as long it fits the checkstyle max length)
> * Add Apache header by default
> * Add "HDDS-XXXX" for each commit message (but this requires the agent to know which ticket is assigned to so might be difficult).
> * Prefer using existing Ozone related glossary instead of inventing new ones unless necessary (things like "control plane", "materialized", etc)
>
> PTAL of these links I found, we can research on the Harness engineering best practices
>
> * [github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)
> * [openai.com/index/harness-engineering](https://openai.com/index/harness-engineering/)
> * [martinfowler.com/articles/harness-engineering.html](https://martinfowler.com/articles/harness-engineering.html)
Thanks @ivandika3 for the suggestions. I have pushed a rewrite. PTAL.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "smengcl (via GitHub)" <gi...@apache.org>.
smengcl merged PR #10302:
URL: https://github.com/apache/ozone/pull/10302
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3263178103
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
Review Comment:
Let's create a AGENTS.md (https://agents.md/) instead and make CLAUDE.md symlink to it so that it can be used by other harness (e.g. Codex). See https://github.com/apache/airflow.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3263187898
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository
+
+Apache Ozone — a scalable, distributed object/file store. This is a multi-module Maven project; root coordinates and current version are in [`pom.xml`](./pom.xml) (`groupId` / `artifactId` / `version`). Two top-level Maven aggregators:
+
+- `hadoop-hdds/` — Hadoop Distributed Data Store: the storage layer (SCM, datanode container service, RocksDB integration, common protocols, crypto, framework). Load-bearing submodules: `server-scm`, `container-service`, `framework`, `managed-rocksdb`, `interface-{admin,client,server}`. See `hadoop-hdds/pom.xml` for the full list.
+- `hadoop-ozone/` — Ozone services and clients on top of HDDS. Load-bearing submodules: `ozone-manager` (OM), `s3gateway`, `recon` (UI/monitoring), `datanode`, `dist` (binary tarball + Docker compose configs), `integration-test*` (Java mini-cluster tests), plus `ozonefs*` (Hadoop-compatible FS adapters). See `hadoop-ozone/pom.xml` for the full list.
+
+The big-picture component split: SCM manages containers/pipelines, OM manages namespace/keys, datanodes serve container data via Ratis (RAFT), Recon provides observability, and S3 Gateway / OzoneFS expose S3 and Hadoop FS APIs. Module boundaries follow this split — when changing a feature, expect edits across `hadoop-hdds/interface-*` (proto), an HDDS server module, and one of `ozone-manager` / `s3gateway` / `recon`. Integration tests for these flows live exclusively in `hadoop-ozone/integration-test*`.
+
+## Build
+
+```bash
+mvn clean install -DskipTests # build + install to local repo (use this when iterating across modules; required before single-module rebuilds resolve correctly)
+mvn clean verify -DskipTests # end-to-end compile/verify without installing — useful as a smoke check, not for iterative dev
+```
+
+Useful flags (composable):
+- `-DskipShade` — skip building the shaded Ozone FS jar (saves time; omit this flag if you need to run filesystem integration tests, which require the shaded jar)
+- `-DskipRecon` — skip Recon Web UI (~2 min faster)
+- `-DskipDocs` — skip Hugo docs build
+- `-Pdist` — build the binary tarball under `hadoop-ozone/dist/target/`
+
+Single-module rebuild after a change (note the leading colon for the artifactId):
+```bash
+mvn -pl :ozone-manager -am install -DskipTests
+```
+
+## Running tests
+
+`hadoop-ozone/dev-support/checks/` contains the same scripts CI runs. Each writes results to `target/<check-name>/` (or `$OUTPUT_DIR`) and exits non-zero on failure. Most useful locally:
+
+- `unit.sh` — pure unit tests (excludes the `ozone-integration-test*` and `mini-chaos-tests` modules)
+- `integration.sh` — Java mini-cluster integration tests (slow)
+- `checkstyle.sh`, `pmd.sh`, `findbugs.sh`, `rat.sh`, `author.sh` — static checks
+- `acceptance.sh` — robot-framework smoketests against a real docker-compose cluster (requires `docker`, `docker-compose`, `jq`)
+- `kubernetes.sh` — limited k8s test suite
+
+Direct Maven equivalents (for running a single test):
+```bash
+# Single test class
+mvn -pl :ozone-manager test -Dtest=TestOzoneManagerLock
+# Single test method
+mvn -pl :ozone-manager test -Dtest=TestOzoneManagerLock#testLockingOrder
+# Integration tests live in their own modules and require -DskipShade etc.
+mvn -pl :ozone-integration-test test -Dtest=TestOmContainerLocationCache -DskipShade -DskipRecon
+```
+
+Re-run flaky tests with the `test-flaky` profile (CI does this): `integration.sh -Ptest-flaky` adds `-Dsurefire.rerunFailingTestsCount=5`.
+
+`build.sh` honors `FAIL_FAST=true`, `ITERATIONS=N`, and `OZONE_WITH_COVERAGE=true` env vars; pass extra Maven args after the script name.
+
+## Running a local cluster
+
+After a `-Pdist` build:
+```bash
+cd hadoop-ozone/dist/target/ozone-*-SNAPSHOT/compose/ozone
+OZONE_REPLICATION_FACTOR=3 ./run.sh -d
+```
+`hadoop-ozone/dist/src/main/compose/` has many topologies (`ozone-ha`, `ozonesecure`, `upgrade`, `xcompat`, etc.). For IDE-launched components there are pre-baked IntelliJ run configs in `.run/`; the documented startup order is SCM init → SCM → OM init → OM → Recon → datanodes.
+
+## Conventions and PR workflow
+
+The authoritative source is [`CONTRIBUTING.md`](./CONTRIBUTING.md). Highlights worth surfacing here:
+
+- PR titles start with the Jira id (e.g. `HDDS-12345. Short description`); every change needs an `HDDS-NNNN` Jira.
+- Update branches via `git merge --no-edit origin/master`, **not** rebase; avoid force-push.
+- 2-space indent, 120-char lines, Apache license header on most files (enforced by Checkstyle and RAT — Markdown excludes are managed in `dev-support/rat/rat-exclusions.txt`); no `@author` tags. Checkstyle config: `hadoop-hdds/dev-support/checkstyle/checkstyle.xml`.
+- For non-trivial features, follow the OEP (Ozone Enhancement Proposal) process — design docs in Markdown.
+- Before wrapping up a change (e.g. before posting a PR), run `./hadoop-ozone/dev-support/checks/checkstyle.sh` locally to catch violations — otherwise the checkstyle CI job will fail immediately on the PR. `rat.sh` is also worth running if you've added new file types.
Review Comment:
Also add the "Generated by: <MODEL> <MODEL_VERSION>" based on the https://www.apache.org/legal/generative-tooling.html
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3270705555
##########
AGENTS.md:
##########
@@ -0,0 +1,80 @@
+# AGENTS.md
Review Comment:
Yes, but I think we can address this in the future. I would prefer if we develop our own Ozone-related skills (e.g. Cassandra bug hunting skills https://github.com/apache/cassandra/pull/4794) instead of using the generic skills like https://github.com/obra/superpowers / https://github.com/mattpocock/skills / https://github.com/addyosmani/agent-skills
And for skills, let's standardize to something like https://agentskills.io instead of Cursor specific formats.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3270705555
##########
AGENTS.md:
##########
@@ -0,0 +1,80 @@
+# AGENTS.md
Review Comment:
Yes, but I think we can address this in the future. I would prefer if we develop our own Ozone-related skills (e.g. Cassandra bug hunting skills https://github.com/apache/cassandra/pull/4794) instead of using the generic skills like https://github.com/obra/superpowers
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3270701410
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository
+
+Apache Ozone — a scalable, distributed object/file store. This is a multi-module Maven project; root coordinates and current version are in [`pom.xml`](./pom.xml) (`groupId` / `artifactId` / `version`). Two top-level Maven aggregators:
+
+- `hadoop-hdds/` — Hadoop Distributed Data Store: the storage layer (SCM, datanode container service, RocksDB integration, common protocols, crypto, framework). Load-bearing submodules: `server-scm`, `container-service`, `framework`, `managed-rocksdb`, `interface-{admin,client,server}`. See `hadoop-hdds/pom.xml` for the full list.
+- `hadoop-ozone/` — Ozone services and clients on top of HDDS. Load-bearing submodules: `ozone-manager` (OM), `s3gateway`, `recon` (UI/monitoring), `datanode`, `dist` (binary tarball + Docker compose configs), `integration-test*` (Java mini-cluster tests), plus `ozonefs*` (Hadoop-compatible FS adapters). See `hadoop-ozone/pom.xml` for the full list.
+
+The big-picture component split: SCM manages containers/pipelines, OM manages namespace/keys, datanodes serve container data via Ratis (RAFT), Recon provides observability, and S3 Gateway / OzoneFS expose S3 and Hadoop FS APIs. Module boundaries follow this split — when changing a feature, expect edits across `hadoop-hdds/interface-*` (proto), an HDDS server module, and one of `ozone-manager` / `s3gateway` / `recon`. Integration tests for these flows live exclusively in `hadoop-ozone/integration-test*`.
+
+## Build
+
+```bash
+mvn clean install -DskipTests # build + install to local repo (use this when iterating across modules; required before single-module rebuilds resolve correctly)
+mvn clean verify -DskipTests # end-to-end compile/verify without installing — useful as a smoke check, not for iterative dev
+```
+
+Useful flags (composable):
+- `-DskipShade` — skip building the shaded Ozone FS jar (saves time; omit this flag if you need to run filesystem integration tests, which require the shaded jar)
+- `-DskipRecon` — skip Recon Web UI (~2 min faster)
+- `-DskipDocs` — skip Hugo docs build
+- `-Pdist` — build the binary tarball under `hadoop-ozone/dist/target/`
Review Comment:
Sorry what I meant is we keep it, but we can specify in the markdown that we should use these options when building locally.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on PR #10302:
URL: https://github.com/apache/ozone/pull/10302#issuecomment-4493717918
> This is generated using /init command in Claude Code. Using Opus 4.7 xhigh.
I think using the AGENTS.md using Claude Code /init is not advisable. See https://www.humanlayer.dev/blog/writing-a-good-claude-md for the reasoning.
PTAL of these links I found, we can research on the Harness engineering best practices
- https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
- https://openai.com/index/harness-engineering/
- https://martinfowler.com/articles/harness-engineering.html
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "yandrey321 (via GitHub)" <gi...@apache.org>.
yandrey321 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3269068732
##########
AGENTS.md:
##########
@@ -0,0 +1,80 @@
+# AGENTS.md
Review Comment:
it would be nice to add skills and rules files for Cursor:
https://cursor.com/docs/skills & https://cursor.com/docs/rules
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "smengcl (via GitHub)" <gi...@apache.org>.
smengcl commented on PR #10302:
URL: https://github.com/apache/ozone/pull/10302#issuecomment-4678121726
Thanks @ivandika3 @yandrey321 @jojochuang for reviewing this. I will merge this as a start.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3270705555
##########
AGENTS.md:
##########
@@ -0,0 +1,80 @@
+# AGENTS.md
Review Comment:
Yes, but I think we can address this in the future. I would prefer if we develop our own Ozone-related skills (e.g. Cassandra bug hunting skills https://github.com/apache/cassandra/pull/4794 or backporting skills for release process) instead of using the generic skills like https://github.com/obra/superpowers / https://github.com/mattpocock/skills / https://github.com/addyosmani/agent-skills
And for skills, let's standardize to something like https://agentskills.io instead of Cursor specific formats.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add AGENTS.md and CLAUDE.md [ozone]
Posted by "jojochuang (via GitHub)" <gi...@apache.org>.
jojochuang commented on PR #10302:
URL: https://github.com/apache/ozone/pull/10302#issuecomment-4512766966
Great proposal! I'd also like to propose to incorporate some ideas from https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md
Specifically, a typical problem is the coding agents making unnecessary changes. This CLAUDE.md reduces the amount of code churns.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add CLAUDE.md [ozone]
Posted by "ivandika3 (via GitHub)" <gi...@apache.org>.
ivandika3 commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3263152494
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository
+
+Apache Ozone — a scalable, distributed object/file store. This is a multi-module Maven project; root coordinates and current version are in [`pom.xml`](./pom.xml) (`groupId` / `artifactId` / `version`). Two top-level Maven aggregators:
+
+- `hadoop-hdds/` — Hadoop Distributed Data Store: the storage layer (SCM, datanode container service, RocksDB integration, common protocols, crypto, framework). Load-bearing submodules: `server-scm`, `container-service`, `framework`, `managed-rocksdb`, `interface-{admin,client,server}`. See `hadoop-hdds/pom.xml` for the full list.
+- `hadoop-ozone/` — Ozone services and clients on top of HDDS. Load-bearing submodules: `ozone-manager` (OM), `s3gateway`, `recon` (UI/monitoring), `datanode`, `dist` (binary tarball + Docker compose configs), `integration-test*` (Java mini-cluster tests), plus `ozonefs*` (Hadoop-compatible FS adapters). See `hadoop-ozone/pom.xml` for the full list.
+
+The big-picture component split: SCM manages containers/pipelines, OM manages namespace/keys, datanodes serve container data via Ratis (RAFT), Recon provides observability, and S3 Gateway / OzoneFS expose S3 and Hadoop FS APIs. Module boundaries follow this split — when changing a feature, expect edits across `hadoop-hdds/interface-*` (proto), an HDDS server module, and one of `ozone-manager` / `s3gateway` / `recon`. Integration tests for these flows live exclusively in `hadoop-ozone/integration-test*`.
+
+## Build
+
+```bash
+mvn clean install -DskipTests # build + install to local repo (use this when iterating across modules; required before single-module rebuilds resolve correctly)
+mvn clean verify -DskipTests # end-to-end compile/verify without installing — useful as a smoke check, not for iterative dev
+```
+
+Useful flags (composable):
+- `-DskipShade` — skip building the shaded Ozone FS jar (saves time; omit this flag if you need to run filesystem integration tests, which require the shaded jar)
+- `-DskipRecon` — skip Recon Web UI (~2 min faster)
+- `-DskipDocs` — skip Hugo docs build
+- `-Pdist` — build the binary tarball under `hadoop-ozone/dist/target/`
Review Comment:
We can prompt the model to use these options when building locally.
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
Review Comment:
Let's create a AGENTS.md (https://agents.md/) instead and make CLAUDE.md symlink to it so that it can be used by other harness (e.g. Codex). See https://github.com/apache/airflow and other Apache projects.
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org
Re: [PR] HDDS-15316. Add CLAUDE.md [ozone]
Posted by "smengcl (via GitHub)" <gi...@apache.org>.
smengcl commented on code in PR #10302:
URL: https://github.com/apache/ozone/pull/10302#discussion_r3268429016
##########
CLAUDE.md:
##########
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository
+
+Apache Ozone — a scalable, distributed object/file store. This is a multi-module Maven project; root coordinates and current version are in [`pom.xml`](./pom.xml) (`groupId` / `artifactId` / `version`). Two top-level Maven aggregators:
+
+- `hadoop-hdds/` — Hadoop Distributed Data Store: the storage layer (SCM, datanode container service, RocksDB integration, common protocols, crypto, framework). Load-bearing submodules: `server-scm`, `container-service`, `framework`, `managed-rocksdb`, `interface-{admin,client,server}`. See `hadoop-hdds/pom.xml` for the full list.
+- `hadoop-ozone/` — Ozone services and clients on top of HDDS. Load-bearing submodules: `ozone-manager` (OM), `s3gateway`, `recon` (UI/monitoring), `datanode`, `dist` (binary tarball + Docker compose configs), `integration-test*` (Java mini-cluster tests), plus `ozonefs*` (Hadoop-compatible FS adapters). See `hadoop-ozone/pom.xml` for the full list.
+
+The big-picture component split: SCM manages containers/pipelines, OM manages namespace/keys, datanodes serve container data via Ratis (RAFT), Recon provides observability, and S3 Gateway / OzoneFS expose S3 and Hadoop FS APIs. Module boundaries follow this split — when changing a feature, expect edits across `hadoop-hdds/interface-*` (proto), an HDDS server module, and one of `ozone-manager` / `s3gateway` / `recon`. Integration tests for these flows live exclusively in `hadoop-ozone/integration-test*`.
+
+## Build
+
+```bash
+mvn clean install -DskipTests # build + install to local repo (use this when iterating across modules; required before single-module rebuilds resolve correctly)
+mvn clean verify -DskipTests # end-to-end compile/verify without installing — useful as a smoke check, not for iterative dev
+```
+
+Useful flags (composable):
+- `-DskipShade` — skip building the shaded Ozone FS jar (saves time; omit this flag if you need to run filesystem integration tests, which require the shaded jar)
+- `-DskipRecon` — skip Recon Web UI (~2 min faster)
+- `-DskipDocs` — skip Hugo docs build
+- `-Pdist` — build the binary tarball under `hadoop-ozone/dist/target/`
Review Comment:
Do you mean we should remove this section? Or keep it here
--
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: issues-unsubscribe@ozone.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org