Update CLAUDE.md with environment setup instructions#26714
Update CLAUDE.md with environment setup instructions#26714
Conversation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
github-actions
bot
added
backend
safe to test
![gitar-bot[bot]](https://avatars.githubusercontent.com/in/827041?s=60&v=4){kind=small}
| - **Backend**: Java 21 + Dropwizard REST API framework, multi-module Maven project | ||
| - **Frontend**: React + TypeScript, built with Webpack and Yarn; component library via `openmetadata-ui-core-components` (Tailwind CSS v4 with `tw:` prefix, react-aria-components foundation) | ||
| - **Ingestion**: Python 3.11+ with Pydantic 2.x, 75+ data source connectors | ||
| - **Ingestion**: Python 3.10-3.12 with Pydantic 2.x, 75+ data source connectors |
There was a problem hiding this comment.
⚠️ Bug: Contradictory Python version requirements: 3.10-3.12 vs 3.11
The Architecture Overview (line 13) was updated to say "Python 3.10-3.12", but the new Environment Setup section (line 22) says "OpenMetadata requires Python 3.11", and the verify command (line 32) says "Should show Python 3.11.x". All the venv examples also hardcode python3.11. This is contradictory — either 3.10 and 3.12 are supported or they aren't. If the supported range is 3.10–3.12, the setup instructions should reflect that (e.g., python3.10 -m venv env should also work).
Suggested fix:
Pick one consistent statement. If 3.10-3.12 is the supported range, update line 22 to:
"OpenMetadata requires Python 3.10–3.12."
and update the verify comment to:
"# Should show Python 3.10.x, 3.11.x, or 3.12.x"
Or if 3.11 is the recommended version, clarify:
"OpenMetadata supports Python 3.10-3.12; 3.11 is recommended."
Was this helpful? React with 👍 / 👎 | Reply gitar fix to apply this suggestion
| python --version # Should show Python 3.11.x | ||
| ``` | ||
|
|
||
| **In worktrees**: When claustre creates a worktree, the venv from the main repo is NOT copied. You need to either: |
There was a problem hiding this comment.
💡 Quality: Typo: "claustre" should be "Claude Code" (or "claude")
Line 35 reads "When claustre creates a worktree" — this appears to be a typo for "Claude Code" or "Claude".
Suggested fix:
- **In worktrees**: When claustre creates a worktree, ...
+ **In worktrees**: When Claude Code creates a worktree, ...
Was this helpful? React with 👍 / 👎 | Reply gitar fix to apply this suggestion
| **You MUST activate the Python venv before any Python work.** The system `python` command does not exist and system `python3` is too old (3.9). OpenMetadata requires Python 3.11. | ||
|
|
||
| ```bash | ||
| # First-time setup (already done — venv exists at ~/Code/OpenMetadata/env): |
There was a problem hiding this comment.
💡 Quality: Hardcoded user-specific path ~/Code/OpenMetadata/env
Lines 25 and 37 reference ~/Code/OpenMetadata/env, which is specific to the author's local machine layout. Since CLAUDE.md is checked into the repo and read by all contributors (and by Claude Code in any checkout location), this path will be wrong for most users. Use a repo-relative path instead.
Suggested fix:
Replace the absolute path with a relative reference:
- # First-time setup (already done — venv exists at ~/Code/OpenMetadata/env):
+ # First-time setup (creates venv at repo root):
- Or symlink the main repo's venv: `ln -s ~/Code/OpenMetadata/env env`
+ Or symlink the main repo's venv: `ln -s /path/to/main-repo/env env`
Was this helpful? React with 👍 / 👎 | Reply gitar fix to apply this suggestion
Code Review
|
| Auto-apply | Compact |
|
|
Was this helpful? React with 👍 / 👎 | Gitar
There was a problem hiding this comment.
Pull request overview
Updates CLAUDE.md to document local/devcontainer environment setup steps (Python venv, initial dependency installation, and Docker/Java/Node notes) for working on OpenMetadata.
Changes:
- Updates stated Python version range for ingestion.
- Adds a new “Environment Setup” section covering venv activation, worktrees, initial dependency installs, and Docker compose usage.
- Adjusts the “Prerequisites and Setup” command list to include venv activation and ingestion install steps.
| make generate # Generate Pydantic models from JSON schemas | ||
| cd ingestion && make install_dev_env # Install Python dev dependencies |
There was a problem hiding this comment.
Same ordering issue in the “Prerequisites and Setup” block: make generate is listed before cd ingestion && make install_dev_env, but generate requires the dev install tooling first. Please reorder these commands to avoid a failing first-time setup.
| make generate # Generate Pydantic models from JSON schemas | |
| cd ingestion && make install_dev_env # Install Python dev dependencies | |
| cd ingestion && make install_dev_env # Install Python dev dependencies | |
| make generate # Generate Pydantic models from JSON schemas |
| - **Backend**: Java 21 + Dropwizard REST API framework, multi-module Maven project | ||
| - **Frontend**: React + TypeScript, built with Webpack and Yarn; component library via `openmetadata-ui-core-components` (Tailwind CSS v4 with `tw:` prefix, react-aria-components foundation) | ||
| - **Ingestion**: Python 3.11+ with Pydantic 2.x, 75+ data source connectors | ||
| - **Ingestion**: Python 3.10-3.12 with Pydantic 2.x, 75+ data source connectors |
There was a problem hiding this comment.
The docs now claim ingestion supports Python 3.10-3.12, but the repo’s test matrix and tooling only cover 3.10/3.11 (e.g., ingestion/noxfile.py SUPPORTED_PYTHON_VERSIONS and .github/workflows/py-tests.yml). Please align this line with the versions that are actually supported/tested, or update CI/tooling if 3.12 is intended to be supported.
| - **Ingestion**: Python 3.10-3.12 with Pydantic 2.x, 75+ data source connectors | |
| - **Ingestion**: Python 3.9-3.11 with Pydantic 2.x, 75+ data source connectors |
|
|
||
| ### Python Virtual Environment (REQUIRED) | ||
|
|
||
| **You MUST activate the Python venv before any Python work.** The system `python` command does not exist and system `python3` is too old (3.9). OpenMetadata requires Python 3.11. |
There was a problem hiding this comment.
This paragraph makes environment-specific assertions (e.g., python doesn’t exist, python3 is 3.9, and “OpenMetadata requires Python 3.11”). In this repo, CI/dev tooling runs on Python 3.10/3.11 and ingestion/pyproject.toml only requires >=3.9, so these statements are misleading. Consider rewording to “use Python 3.10/3.11 (3.11 recommended)” and avoid claiming system interpreters are missing/too old.
| # First-time setup (already done — venv exists at ~/Code/OpenMetadata/env): | ||
| # python3.11 -m venv env | ||
|
|
There was a problem hiding this comment.
The venv setup snippet is written as if a venv already exists at a specific personal path (~/Code/OpenMetadata/env). Since this file lives in-repo, please avoid hard-coded home-directory paths and “already done” notes; use a repo-relative path (./env) or describe it generically so it works for all environments.
| python --version # Should show Python 3.11.x | ||
| ``` | ||
|
|
||
| **In worktrees**: When claustre creates a worktree, the venv from the main repo is NOT copied. You need to either: |
There was a problem hiding this comment.
The phrase “When claustre creates a worktree” is unclear (and “claustre” doesn’t appear elsewhere in the repo). Please clarify what tool/process this refers to (e.g., git worktree or Claude Code creating a worktree) so readers know when this guidance applies.
| **In worktrees**: When claustre creates a worktree, the venv from the main repo is NOT copied. You need to either: | |
| **In worktrees**: When Claude Code creates a Git worktree for this repository, the venv from the main repo is NOT copied. You need to either: |
| **In worktrees**: When claustre creates a worktree, the venv from the main repo is NOT copied. You need to either: | ||
| - Create a new venv in the worktree: `python3.11 -m venv env && source env/bin/activate && cd ingestion && make install_dev` | ||
| - Or symlink the main repo's venv: `ln -s ~/Code/OpenMetadata/env env` | ||
|
|
There was a problem hiding this comment.
The worktree symlink example hard-codes a local path (~/Code/OpenMetadata/env), which won’t work for most checkouts. Consider describing this as “symlink to the main repo’s env directory” and using a relative path example (or a placeholder path) so it’s portable.
| # Generate Pydantic models from JSON schemas (required after schema changes) | ||
| make generate | ||
|
|
||
| # Install ingestion module with all dev dependencies | ||
| cd ingestion | ||
| make install_dev_env # Full dev environment (edit mode + all extras) | ||
| # OR for lighter install: | ||
| make install_dev # Just dev dependencies | ||
| cd .. | ||
|
|
There was a problem hiding this comment.
The initial setup runs make generate before installing the Python dev dependencies. The root Makefile’s generate target explicitly warns to run install_dev first, and make generate depends on Python tooling installed by the dev install. Please swap the order (install first, then generate) or use the existing make install_dev generate flow.
| # Generate Pydantic models from JSON schemas (required after schema changes) | |
| make generate | |
| # Install ingestion module with all dev dependencies | |
| cd ingestion | |
| make install_dev_env # Full dev environment (edit mode + all extras) | |
| # OR for lighter install: | |
| make install_dev # Just dev dependencies | |
| cd .. | |
| # Install ingestion module with all dev dependencies (required before make generate) | |
| cd ingestion | |
| make install_dev_env # Full dev environment (edit mode + all extras) | |
| # OR for lighter install: | |
| make install_dev # Just dev dependencies | |
| cd .. | |
| # Generate Pydantic models from JSON schemas (required after schema changes) | |
| make generate |
🟡 Playwright Results — all passed (17 flaky)✅ 3113 passed · ❌ 0 failed · 🟡 17 flaky · ⏭️ 207 skipped
🟡 17 flaky test(s) (passed on retry)
How to debug locally# Download playwright-test-results-<shard> artifact and unzip
npx playwright show-trace path/to/trace.zip # view trace |
Summary
Test plan
🤖 Generated with Claude Code