|
| 1 | +# Repository instructions |
| 2 | + |
| 3 | +Guidance for coding agents working in `HydrologicEngineeringCenter/cwms-cli`. |
| 4 | + |
| 5 | +- Never push to `origin` unless the user explicitly says they are ready for |
| 6 | + that push. |
| 7 | +- Use JDK 21 or newer for new work that is not intended to run on T7 systems. |
| 8 | + On Windows, use JDK 21 at `C:\Program Files\Java\jdk-21`. On Linux or other |
| 9 | + Unix-like systems, select an installed JDK 21 or newer through `JAVA_HOME`. |
| 10 | + Use another Java version only when the target or task requires it. |
| 11 | +- Use the `.devcontainer` Linux/Python 3.12 environment for changes involving |
| 12 | + time zones, paths, native libraries, HEC-DSS, or other operating-system- |
| 13 | + dependent behavior. |
| 14 | +- Run the full dev-container test suite with |
| 15 | + `devcontainer exec --workspace-folder . poetry run pytest -q` when the dev |
| 16 | + container is available. The standard CI matrix separately covers Python 3.9 |
| 17 | + and Python 3.12 package compatibility. |
| 18 | + |
| 19 | +## Terminal colors |
| 20 | + |
| 21 | +- Use the shared helpers in `cwmscli.utils.colors` for user-facing terminal |
| 22 | + color. Prefer `colors.ok`, `colors.warn`, `colors.err`, and `colors.dim` for |
| 23 | + their semantic cases, or `colors.c(text, color, bright=...)` when a specific |
| 24 | + color is needed. |
| 25 | +- Do not embed ANSI escape sequences or initialize Colorama in individual |
| 26 | + commands. Global logging setup owns Colorama initialization and calls |
| 27 | + `colors.set_enabled(...)` so `--no-color`, `--log-file`, and non-TTY output |
| 28 | + remain consistent. |
| 29 | +- Keep the text meaningful without color. Color should clarify status or |
| 30 | + structure, not carry information that disappears when color is disabled. |
| 31 | +- Reuse the existing conventions: green for success, yellow for warnings, |
| 32 | + red for errors, cyan or blue for identifiers and commands, and dim text for |
| 33 | + secondary detail. |
| 34 | +- When testing colored output, cover the plain-text behavior first. Enable the |
| 35 | + shared color helper explicitly only in tests that need to assert escape codes, |
| 36 | + and restore its state afterward. |
| 37 | + |
| 38 | +## Ownership metadata |
| 39 | + |
| 40 | +- Use `maintainers.toml` as the primary configuration file for maintainer names, |
| 41 | + CLI ownership, documentation maintainer notes, package authors, and |
| 42 | + CODEOWNERS rules. Do not edit generated ownership files directly. |
| 43 | +- When adding, renaming, moving, or removing a command, implementation area, |
| 44 | + documentation page, test area, workflow, or other substantial path, review |
| 45 | + and update the corresponding entries in `maintainers.toml` in the same |
| 46 | + change. |
| 47 | +- Keep the fallback `*` CODEOWNERS rule first. GitHub applies the last matching |
| 48 | + rule, so more-specific rules must appear after the fallback. |
| 49 | +- Prefer explicit CODEOWNERS rules for implementation, documentation, and tests |
| 50 | + that share the same maintainer. Keep ownership-governance files themselves |
| 51 | + explicitly owned. |
| 52 | +- After changing `maintainers.toml`, run |
| 53 | + `poetry run python scripts/sync_ownership.py`, review every generated change, |
| 54 | + and then run `poetry run python scripts/sync_ownership.py --check`. |
| 55 | +- Before completing ownership changes, verify that configured command names and |
| 56 | + CODEOWNERS paths still exist and that GitHub reports no CODEOWNERS errors. |
| 57 | + |
| 58 | +## Git safety |
| 59 | + |
| 60 | +- Never push to `origin` unless the user explicitly authorizes the push. |
| 61 | +- Do not use `codex`, `agent`, AI-related terms, or similar prefixes in branch |
| 62 | + names. Use a short, human-readable branch name tied to the concern. |
| 63 | +- Inspect untracked files before staging and leave unrelated work untouched. |
0 commit comments