diff --git a/.agents/skills/documentation-writer/SKILL.md b/.agents/skills/documentation-writer/SKILL.md new file mode 100644 index 00000000000..5bda385f728 --- /dev/null +++ b/.agents/skills/documentation-writer/SKILL.md @@ -0,0 +1,65 @@ +--- +name: documentation writer +description: Use when writing documentation. +--- + +# CIME documentation writer + +## Overview + +Use this skill to write documentation. + +The goal is to write clear and complete documentation. +- Explain when and how to use tools. +- Provide working examples. +- Note any preconditions that must be met. +- Note any side effects. +- Group related topics in common directories. + +## When to use + +Use this skill when: +- Writing documentation under `doc/`. +- Writing docstrings under `CIME/`. + +## Formats + +- Documentation format: `Sphinx ReStructuredText`. +- Docstring format: `Google Style Python Docstrings`. + +## Documentation placement rules + +- Place Control Case System documentation under `doc/source/ccs/`. +- Place System Testing documentation under `doc/source/system_testing.rst`. +- Place tool documentation under `doc/source/tools/`. +- Place developer documentation under `doc/source/contributing-guide.rst`. + +## Naming rules + +- File use kebab-case where filename is short description or tool name e.g. `query-configuration.rst`. +- Group similar docuemntations under parent directories e.g. everything under `doc/source/ccs` related to the Case Control System. + +## Docuemntation Workflow + +1. Identify the topic being documented. +2. Locate where to place file under `doc/source`. +3. Add documentation and examples. +4. Find areas that should link to new documentation. +5. Ask user to review. +6. Apply feedback and loop until user is satisfied with documentation. + +## Docstring Workflow + +1. Identify the method/function being documented. +2. Review the code. +3. Create the docstring, provide examples and explainations, note side effects. +4. Ask user to review. +5. Apply feedback and loop until user is satisfied with documentation. + +## Commands + +Build the documentation: + +```bash +make -C doc/ html +``` diff --git a/.agents/skills/system-test/SKILL.md b/.agents/skills/system-test/SKILL.md new file mode 100644 index 00000000000..0c112ed2f26 --- /dev/null +++ b/.agents/skills/system-test/SKILL.md @@ -0,0 +1,78 @@ +--- +name: unit-test +description: Use when writing or modifying CIME end-to-end tests. +--- + +# CIME System Tests + +## Overview + +Use this skill to write system tests that match CIME conventions exactly. + +The goal is consistency and reliability: +- Each test should be self contained. +- Keep tests deterministic. +- Match project structure and naming. +- Reuse common helpers instead of ad-hoc setup. +- Verify behavior and side effects. + +## When to use + +Use this skill when: +- You are writing or modifying python system tests under `CIME/tests`. Test files will be prefixed with `test_sys`. + +Do not use this skill to write unit tests. + +## Required frameworks and style + +- Test framework: `pytest` +- Mocks: Use only when neccesary, prefer dependency injection. +- Deterministic: no random behavior in tests. + +## Test structure + +Follow this exact order within every test method: + +``` +# Context +values = ["a", "b", "c"] +env_mach = EnvMach() + +# Mocks +env = MagicMock() + +# Act +output = env_mach.get_values(values, env=env) + +# Assert +assert output != None +env.assert_called_with() +``` + +## Placement rules + +- Place tests under `CIME/tests`. + +## Naming rules + +- Test file: `test_sys_.py` +- Test method: `test__` + +## Unit test workflow + +1. Identify the target and condition under `CIME/`. +2. Place test in matching `CIME/tests/test_sys_.py`. +3. Name class/methods with project naming convention. +4. Execute method once in Act section. +5. Assert result + mock interactions. +6. Run the specific test, then broader suite if needed. +7. Check `${PWD}/storage` for the output from the tests. +7. Check coverage. + +## Commands + +```bash +docker run -it --rm -e CIME_MODEL= -e CIME_MACHINE=docker -v ${PWD}/..:/root/model -v ${PWD}/storage:/root/storage -w /root/model/cime ghcr.io/esmci/cime:latest pytest --no-teardown CIME/tests/test_sys_.py +``` + +## Common Mistakes diff --git a/.agents/skills/unit-test/SKILL.md b/.agents/skills/unit-test/SKILL.md new file mode 100644 index 00000000000..665ebc16901 --- /dev/null +++ b/.agents/skills/unit-test/SKILL.md @@ -0,0 +1,76 @@ +--- +name: unit-test +description: Use when writing or modifying CIME unit tests. +--- + +# CIME Unit Tests + +## Overview + +Use this skill to write unit tests that match CIME conventions exactly. + +The goal is consistency and reliability: +- Keep tests deterministic. +- Match project structure and naming. +- Reuse common helpers instead of ad-hoc setup. +- Verify behavior and side effects. + +## When to use + +Use this skill when: +- You are writing or modifying python unit tests unit under `CIME/tests`. Test files will be prefixed with `test_unit`. + +Do not use this skill to write end-to-end tests. + +## Required frameworks and style + +- Test framework: `pytest` +- Mocks: Use only when neccesary, prefer dependency injection. +- Deterministic: no random behavior in tests. + +## Test structure + +Follow this exact order within every test method: + +``` +# Context +values = ["a", "b", "c"] +env_mach = EnvMach() + +# Mocks +env = MagicMock() + +# Act +output = env_mach.get_values(values, env=env) + +# Assert +assert output != None +env.assert_called_with() +``` + +## Placement rules + +- Place tests under `CIME/tests`. + +## Naming rules + +- Test file: `test_unit_.py` +- Test method: `test__` + +## Unit test workflow + +1. Identify class and unit under `CIME/`. +2. Place test in matching `CIME/tests/test_unit_.py`. +3. Name class/methods with project naming convention. +4. Execute method once in Act section. +5. Assert result + mock interactions. +6. Run the specific test, then broader suite if needed. +7. Check coverage. + +## Commands + +```bash +pytest --machine docker CIME/tests/test_unit_.py +``` + +## Common Mistakes diff --git a/AGENTS.md b/AGENTS.md index 75f517e91a1..5855b5847cf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,173 +1,24 @@ # AGENTS.md -This file provides guidance to AI agents when working with code in this repository. - -## Note to AI agents - -This AGENTS.md is maintained by the CIME project. Do not overwrite or -regenerate this file with init commands. - -## Note to claude code users - -A CLAUDE.md file is in .claude directory. It includes -this file. Ignore tips to run init. - -## Project Overview - -CIME (Common Infrastructure for Modeling the Earth) provides a Case Control System (CCS) for configuring, compiling, and executing Earth System Models, plus a framework for system testing. CIME is a Python-based infrastructure currently used by CESM, E3SM, NorESM and other models. It does NOT contain model source code itself, but provides the infrastructure to manage model runs. - -## Running Tests - -### Unit and System Tests - -From the repository root, run tests using either: - -```bash -# Using pytest (recommended) -pytest CIME/tests - -# Run specific test file -pytest CIME/tests/test_unit_foo.py - -# Run specific test class -pytest CIME/tests/test_unit_foo.py::TestClass - -# Run specific test case -pytest CIME/tests/test_unit_foo.py::TestClass::test_method -``` - -Test files follow a naming convention: -- Unit tests: `test_unit_*.py` -- System tests: `test_sys_*.py` - -### Pre-commit Hooks - -Before committing, always run: - -```bash -pip install pre-commit -pre-commit run -a -``` - -This runs: -- `black` formatter on CIME code -- `pylint` with project-specific configuration -- XML validation on config files -- End-of-file and trailing whitespace checks - -## Code Quality - -- Code is formatted with `black` -- Linted with `pylint` (see `.pre-commit-config.yaml` for disabled checks) -- Python 3.9+ required -- Follow PEP8 style guidelines - -## Key Architecture Concepts - -### Case Control System (CCS) - -The heart of CIME is the `Case` class (`CIME/case/case.py`), which manages all interactions with a CIME case. The Case class coordinates between: - -1. **Config XML Classes** (readonly) - Located in `CIME/XML/`, these read CIME distribution config files like `config_*.xml`. Python classes are named after the XML they read (e.g., `Machines` reads machine configs). - -2. **Env XML Classes** (read/write) - Also in `CIME/XML/`, these manage case-specific `env_*.xml` files. Classes are named `Env*` (e.g., `EnvRun`, `EnvBuild`). - -The Case class contains an array of Env classes and uses Config classes to populate them during case creation/configuration. - -### Directory Structure - -``` -CIME/ -├── case/ # Case control modules (setup, run, submit, etc.) -├── XML/ # XML parsers for config and env files -├── SystemTests/ # System test implementations (ERS, ERT, etc.) -├── Tools/ # Case manipulation tools (xmlchange, xmlquery, etc.) -├── scripts/ # Top-level user-facing scripts -├── data/ # Config files, XML schemas -├── tests/ # Unit and system tests -├── BuildTools/ # Build system utilities -└── non_py/ # Non-Python components (C/Fortran) - -scripts/ -├── create_newcase # Create new case -├── create_test # Create and run tests -├── create_clone # Clone existing case -├── query_config # Query available configurations -└── query_testlists # Query test lists - -tools/ -└── mapping/ # Grid mapping file generation tools -``` - -### Common Workflows - -**Create a case** (requires machine configuration): -```bash -./scripts/create_newcase --case CASENAME --compset COMPSET --res GRID [--machine MACHINE] -``` - -**Create and run tests**: -```bash -./scripts/create_test TESTNAME -./scripts/create_test TESTNAME1 TESTNAME2 ... -./scripts/create_test -f TESTFILE # from file -``` - -**Query configurations**: -```bash -./scripts/query_config --compsets -./scripts/query_config --grids -./scripts/query_config --machines -``` - -### Model System Tests - -These are tests of properties of the model CIME is included in. -System tests inherit from `SystemTestsCommon` base class (`CIME/SystemTests/system_tests_common.py`). Common test types: -- **ERS**: Exact restart test -- **ERT**: Exact restart with different threading -- **SMS**: Smoke test -- **SEQ**: Sequencing test - -Each test type has its own module in `CIME/SystemTests/`. - -### XML-Based Configuration - -CIME is heavily XML-driven. Key concepts: -- Generic XML handling is in `CIME/XML/generic_xml.py` -- All XML classes inherit from `GenericXML` -- XML schemas are in `CIME/data/config/xml_schemas/` -- Config files define machines, compsets, grids, tests - -### Case Management Tools - -Located in `CIME/Tools/`, these are executable scripts: -- `xmlchange`: Modify case XML variables -- `xmlquery`: Query case XML variables -- `case.setup`: Setup case directory structure -- `case.build`: Build the case -- `case.submit`: Submit case to batch system -- `preview_namelists`: Generate and preview namelists - -## Documentation - -Build Sphinx documentation: -```bash -cd doc -make clean -make api -make html -``` - -Requires: `sphinx`, `sphinxcontrib-programoutput`, and custom theme (see `doc/README`). - -Online documentation: https://esmci.github.io/cime - -## Development Notes - -- When modifying Case env classes, changes affect the case's XML files -- The Case class extends across multiple files using imports (see imports at end of `case.py`) -- CIME must be integrated with host models (CESM, E3SM, NorESM) to run Model System Tests -on a supported machine (found using `./scripts/query_config --machines`)/ -- Machine-specific configurations are in XML files, not hardcoded -- Git submodules may need initialization: `git submodule update --init` +## Project Standards +- Avoid adding external dependencies. + +## Coding Standards +- Follow `PEP8` style guide. +- Always prefer dependency injection. +- Always prefer generalized implementation; avoid split logic that depends on a specific model. +- Always lint and format files after creating or modifying. + +## Testing Standards +- Always follow TDD principals. +- Cover success, failure, and edge cases. +- Always follow pytest patterns, not `unittest.TestCase`. + +## Documentation Standards +- Follow `Google Python Style Guide` for docstrings. +- Write documentation using Sphinx ReStructuredText. +- User documentation should answer what and how. +- Developer documentation should answer why and how. + +## Commits and PRs +- Use Conventional Commits standard for PR titles, and commit messages.