From 7d603283f3eb4095ce1025b07d192ad9ce5070f0 Mon Sep 17 00:00:00 2001 From: sadamov Date: Sat, 6 Jun 2026 21:45:02 +0200 Subject: [PATCH 01/10] docs: Add root CONTRIBUTING.md (#407) Re-applies @ANANYA542's PR #407 with two small polishes: - Removed em-dashes (project style is plain hyphens) - Removed the leading space inside the Slack invite link parens - Added the missing CHANGELOG entry under the (unreleased) Maintenance section per the project convention Co-Authored-By: ANANYA542 Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 2 ++ CONTRIBUTING.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a7be915..8736c764 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -72,6 +72,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Maintenance +- Add a root `CONTRIBUTING.md` walking a new contributor from fork to merged PR (issue triage, environment setup pointing at the README install section, pre-commit, code standards, the exact local test command CI runs, PR template / CHANGELOG expectations, Slack + issues for help) [\#407](https://github.com/mllam/neural-lam/pull/407) @ANANYA542 + - Group the existing Neural-LAM citation papers in the README under a `### Core Neural-LAM Publications` subheading for clearer structure [\#633](https://github.com/mllam/neural-lam/pull/633) @HetaviM29 - Add unit tests for `inverse_softplus` covering roundtrip identity (parametrized over `beta`), near-zero clamping, and above-threshold linear passthrough [\#419](https://github.com/mllam/neural-lam/pull/419) @Riteesh-NITT diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..04c4db9a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,61 @@ +# Contributing to Neural-LAM + +Thank you for your interest in contributing to Neural-LAM! +We welcome bug reports, bug fixes, documentation improvements, and new features. + +## Getting started + +1. **Open or find an issue.** Before writing code, open a + [GitHub issue](https://github.com/mllam/neural-lam/issues) describing what + you plan to do. If an issue already exists, comment so others know you are + working on it. New contributors looking for an approachable first task can + filter by the + [`good first issue` label](https://github.com/mllam/neural-lam/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). + +2. **Read the existing discussion.** Review the full issue thread and any + linked PRs - someone may have already proposed a solution or identified a + blocker. + +3. **Set up your environment.** Fork the repo via the GitHub UI, then follow + the [Installing Neural-LAM section of the README](README.md#installing-neural-lam) + using the `--group dev` flag. Then activate the hooks: + + ```bash + pre-commit install + ``` + +## Code standards + +Code quality is enforced automatically by +[pre-commit hooks](.pre-commit-config.yaml) (Black, isort, Flake8, mypy, +Codespell and others). In addition: + +- Add **NumPy-style docstrings** and **type annotations** to every public + function and class. +- Keep new code consistent with the patterns already in the codebase. + +## Before you push + +Run **both** checks locally - they are the same ones CI will run: + +```bash +pre-commit run --all-files +pytest -vv -s --doctest-modules +``` + +> **Note:** The first test run downloads ~50 MB of example data via +> [pooch](https://www.fatiando.org/pooch/). + +## Pull requests + +1. Push your branch and open a PR against `main`. +2. Fill in the + [pull request template](.github/pull_request_template.md) - it contains the + full checklists for authors, reviewers, and assignees, including the + CHANGELOG entry format. +3. A maintainer will review your PR. Small, focused PRs are reviewed faster. + +## Getting help + +- Join the [mllam Slack workspace](https://kutt.to/mllam) +- [Open a GitHub issue](https://github.com/mllam/neural-lam/issues) From 68cb1ca1e86ea7acf843629b18c28474de83e5f6 Mon Sep 17 00:00:00 2001 From: sadamov Date: Mon, 8 Jun 2026 20:57:27 +0200 Subject: [PATCH 02/10] docs: trim AGENTS.md to AI-specific rules, point at CONTRIBUTING.md CONTRIBUTING.md (this PR) now owns the general contributor workflow. Remove the duplicate sections from AGENTS.md (Issues, Pull Requests, Changelog) and add a pointer to CONTRIBUTING.md as the first thing agents should read. Kept and refined the AI-specific rules: - Search before creating issues/PRs (now consolidated to one section with the exact gh search commands). - Re-read the full thread before every action, reload after context gaps - the rule that matters most for agents. - Communication style (terse, no filler ban list). - AI attribution in commit trailers. Also updated the codebase reference to reflect the post-#208 ForecasterModule / Forecaster / StepPredictor hierarchy, and added `pytest -m "not slow"` to the command list (per #651). Net: 91 lines (down from 97), but the AI-specific content is denser. Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 62 +++++++++++++++++++++++++------------------------------ 1 file changed, 28 insertions(+), 34 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dcf05d56..3500b10b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,11 @@ Mandatory rules for AI coding agents. Violations will result in rejected PRs. +**Read [CONTRIBUTING.md](CONTRIBUTING.md) first.** It covers the general workflow that applies to +every contributor (open an issue, fork, set up the environment, run `pre-commit` and `pytest`, +fill in the PR template, add a CHANGELOG entry, monthly dev meeting). Everything there applies. +This file adds the AI-specific rules on top. + --- ## Codebase @@ -14,8 +19,8 @@ Predictions **Key modules:** - `datastore/` — `BaseDatastore` (abstract), `MDPDatastore` (zarr via mllam-data-prep) -- `models/` — `ARModel` (autoregressive base, Lightning) → `BaseGraphModel` (encode-process-decode) - → `GraphLAM` / `HiLAM` / `HiLAMParallel` +- `models/` — `ForecasterModule` (Lightning) → `Forecaster` (`ARForecaster`) → + `StepPredictor` (`GraphLAM` / `HiLAM` / `HiLAMParallel`) - `weather_dataset.py` — `WeatherDataset` + `WeatherDataModule` - `config.py` — YAML config via dataclass-wizard - `create_graph.py` — builds mesh graphs (must run before training) @@ -26,7 +31,7 @@ Config examples: `tests/datastore_examples/` ## Commands -These commands need to be prepended with `uv run` or the virtual env activated with `source .venv/bin/activate` first: +Prepend `uv run` or activate the venv first with `source .venv/bin/activate`: ```bash # Install (PyTorch must be installed first for CUDA variant) @@ -39,6 +44,7 @@ pre-commit run --all-files # black, isort, flake8, mypy, codespell pytest -vv -s --doctest-modules # all pytest tests/test_training.py -vv -s # single file pytest tests/test_training.py::test_fn -vv # single function +pytest -m "not slow" # skip long-running training tests # Run python -m neural_lam.create_graph --config_path --name @@ -50,48 +56,36 @@ W&B auto-disabled in tests. `DummyDatastore` used; example data downloaded from --- -## Rules +## AI-specific rules + +### Search before creating + +Duplicate issues and PRs from AI agents are a recurring problem. Search before opening anything: -### Issues +```bash +gh issue list --state all --search "" +gh pr list --state all --search "" +``` -1. **Search before creating.** Use any of: GitHub UI search, `gh issue list --state all --search ""`, or `curl "https://api.github.com/search/issues?q=+repo:mllam/neural-lam+type:issue"`. Duplicate issues will be closed. -2. **Every PR requires an issue.** No exceptions. Open one first if none exists. -3. **Include minimal example.** Each issue should include a minimal, reproducible example on how to easily recreate a bug, including all necessary module imports and data. Include full traceback if it is a bug-report. +If a PR already exists for the same issue, contribute there rather than opening a competing one. -### Pull Requests +### Re-read the thread before every action -1. **Search before creating.** Use any of: GitHub UI search, `gh pr list --state all --search ""`, or `curl "https://api.github.com/search/issues?q=+repo:mllam/neural-lam+type:pr"`. If a PR exists for the same issue, contribute there. -2. **Link the issue.** PR body must contain `closes #` or `refs #`. Unlinked PRs will be - rejected. -3. **Use the PR template.** Fill in every section of `.github/pull_request_template.md`. Do not - delete or skip sections. -4. **Read the full issue thread before writing code.** Rejected approaches and prior decisions are - there. Ignoring them wastes everyone's time. -5. **Run pre-commit hooks locally.** Linting needs to be done locally before each new commit with e.g. `uvx pre-commit run --all` -6. **Testing Mandate.** Run `pytests tests/` before opening a PR and if tests fail do not open the PR , fix the failure first. +- Re-read the entire issue / PR thread before every comment and every push. No exceptions. +- After a context gap, reload it (`gh issue view ` / `gh pr view ` / + `gh api repos/mllam/neural-lam/pulls//comments`) before acting. +- Never repeat a question already answered or an approach already rejected in the thread. ### Communication - **Terse.** One sentence per point. No preamble. No summaries of visible diffs. -- **No filler.** Ban list: "Great question", "As mentioned above", "I hope this helps", "Let me know - if you have questions", "Happy to help". +- **No filler.** Ban list: "Great question", "As mentioned above", "I hope this helps", "Let me + know if you have questions", "Happy to help". - **No obvious narration.** Do not explain what self-explanatory code does. - **PR descriptions: what changed and why.** Nothing else. - **One question at a time.** No shotgun lists of open-ended questions. -### Context - -- **Re-read the entire thread** before every comment and every push. No exceptions. -- **After a context gap**, reload the full thread (GitHub UI, `gh issue view ` / `gh pr view `, or `curl "https://api.github.com/repos/mllam/neural-lam/issues/"`) before acting. -- **Never repeat** a question already answered or an approach already rejected in the thread. - ### Commits -- Imperative form, matching existing `git log` style. -- One concern per PR. No unrelated changes. -- AI attribution of tool names is mandatory if used and should be mentioned in the commit message trailer as `Co-authored-by ` - -### Changelog - -Every PR must add a line to `CHANGELOG.md` in the section matching the change type (`Added` / `Changed` / `Fixed` / `Maintenance`). -`maintenance`). +- AI attribution is mandatory. Add a `Co-authored-by: ` trailer to every + commit produced with AI assistance. From 140c74894638d8c6e65bfdd61d9f60b1bc1ae185 Mon Sep 17 00:00:00 2001 From: sadamov Date: Mon, 8 Jun 2026 21:02:20 +0200 Subject: [PATCH 03/10] docs: add commit conventions, squash policy, and MIT licence note Three basic must-haves that the contributing guide was missing: - Commit messages: imperative form ("Add X" not "Added X"), matching the existing git log style, one concern per PR. - Squash-merge policy: PR title becomes the commit message on main, PR description becomes the body. Polish those, not the per-commit history. - Licence section: explicit note that Neural-LAM is MIT-licensed and that contributions are made under the same terms. Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRIBUTING.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 978b4146..79869c38 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,7 +73,13 @@ pytest -vv -s --doctest-modules [pull request template](.github/pull_request_template.md) - it contains the full checklists for authors, reviewers, and assignees, including the CHANGELOG entry format. -3. A maintainer will review your PR. Small, focused PRs are reviewed faster. +3. Write commit messages in **imperative form** matching the existing + `git log` style ("Add X" not "Added X"), and keep one concern per PR. +4. PRs land via **squash-and-merge**: the PR title becomes the single commit + message on `main` and the PR description becomes its body. Polish both + before requesting review - per-commit history on your branch is not + preserved in `main`. +5. A maintainer will review your PR. Small, focused PRs are reviewed faster. ## Monthly development meetings @@ -97,3 +103,9 @@ good place to learn where these tools are heading. dev meeting in `#general`. - [Open a GitHub issue](https://github.com/mllam/neural-lam/issues) - best for anything that benefits from a written, searchable record. + +## License + +Neural-LAM is released under the [MIT License](LICENSE.txt). By contributing +to this repository, you agree that your contribution is licensed under the +same terms. From 25b764fba2369999d3e785dc6e1900a6f88964d1 Mon Sep 17 00:00:00 2001 From: sadamov Date: Mon, 8 Jun 2026 21:17:24 +0200 Subject: [PATCH 04/10] docs: trim AGENTS.md further - pointers over duplicated content Per request to make AGENTS.md easy to maintain by avoiding duplication with other docs: - Codebase section: dropped the snapshot module list (which already rots, was still showing pre-#208 names in one version), replaced with a pointer at the README architecture overview and `git log --stat -- neural_lam/` for finding recently-moved files. - Commands section: kept only the create_graph / train_model / --eval CLI entry points (the AI-specific bit) and pointed at CONTRIBUTING.md > Before you push for the standard install / lint / test commands that already live there. - Re-read the thread rule: compressed three bullets to one paragraph, same content. Net: 68 lines (down from 91). Maintenance burden: one paragraph per section, mostly links. Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 61 +++++++++++++++++-------------------------------------- 1 file changed, 19 insertions(+), 42 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3500b10b..a652cdeb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,52 +7,26 @@ every contributor (open an issue, fork, set up the environment, run `pre-commit` fill in the PR template, add a CHANGELOG entry, monthly dev meeting). Everything there applies. This file adds the AI-specific rules on top. ---- - -## Codebase - -Neural-LAM: graph-based neural weather prediction for Limited Area Modeling. Models: `GraphLAM`, -`HiLAM`, `HiLAMParallel`. +## Codebase reference -**Data flow:** Raw zarr/numpy → `Datastore` → `WeatherDataset` → `WeatherDataModule` → Model → -Predictions +See the README architecture overview for the data flow and module map. +`git log --stat -- neural_lam/` shows which files have moved recently - prefer that over any +snapshot, which will rot. -**Key modules:** -- `datastore/` — `BaseDatastore` (abstract), `MDPDatastore` (zarr via mllam-data-prep) -- `models/` — `ForecasterModule` (Lightning) → `Forecaster` (`ARForecaster`) → - `StepPredictor` (`GraphLAM` / `HiLAM` / `HiLAMParallel`) -- `weather_dataset.py` — `WeatherDataset` + `WeatherDataModule` -- `config.py` — YAML config via dataclass-wizard -- `create_graph.py` — builds mesh graphs (must run before training) -- `interaction_net.py` — `InteractionNet` GNN layer (PyG `MessagePassing`) -- `utils.py` — `make_mlp`, normalization helpers +## AI-specific entry-point commands -Config examples: `tests/datastore_examples/` - -## Commands - -Prepend `uv run` or activate the venv first with `source .venv/bin/activate`: +The standard install / lint / test commands are in +[CONTRIBUTING.md > Before you push](CONTRIBUTING.md#before-you-push). The two CLI entry points +agents most often need: ```bash -# Install (PyTorch must be installed first for CUDA variant) -uv pip install --group dev -e . - -# Lint -pre-commit run --all-files # black, isort, flake8, mypy, codespell - -# Test -pytest -vv -s --doctest-modules # all -pytest tests/test_training.py -vv -s # single file -pytest tests/test_training.py::test_fn -vv # single function -pytest -m "not slow" # skip long-running training tests - -# Run python -m neural_lam.create_graph --config_path --name python -m neural_lam.train_model --config_path --model graph_lam --graph python -m neural_lam.train_model --eval test --config_path --load ``` -W&B auto-disabled in tests. `DummyDatastore` used; example data downloaded from S3 on first run. +W&B is auto-disabled in tests. `DummyDatastore` is the in-memory test fixture; example data is +downloaded from S3 on first run. --- @@ -71,10 +45,9 @@ If a PR already exists for the same issue, contribute there rather than opening ### Re-read the thread before every action -- Re-read the entire issue / PR thread before every comment and every push. No exceptions. -- After a context gap, reload it (`gh issue view ` / `gh pr view ` / - `gh api repos/mllam/neural-lam/pulls//comments`) before acting. -- Never repeat a question already answered or an approach already rejected in the thread. +Re-read the full issue / PR thread (including inline review comments via +`gh api repos/mllam/neural-lam/pulls//comments`) before every comment and every push. Never +repeat a question already answered or an approach already rejected. ### Communication @@ -87,5 +60,9 @@ If a PR already exists for the same issue, contribute there rather than opening ### Commits -- AI attribution is mandatory. Add a `Co-authored-by: ` trailer to every - commit produced with AI assistance. +AI attribution is mandatory. Add a `Co-authored-by:` trailer to every commit produced with AI +assistance, e.g.: + +``` +Co-authored-by: Claude Opus 4.7 +``` From 9fbd73eed58c31a620dfd97c0e293ad346e687ac Mon Sep 17 00:00:00 2001 From: sadamov Date: Mon, 8 Jun 2026 21:23:42 +0200 Subject: [PATCH 05/10] docs: add explicit CHANGELOG entry section to CONTRIBUTING.md Per Copilot's review on #407: the AGENTS.md intro claims CONTRIBUTING.md covers "add a CHANGELOG entry", but CONTRIBUTING.md only mentioned the CHANGELOG in passing under the PR template description. Promote it to its own section with the format and a real example, since adding a CHANGELOG entry is a hard project rule (it's listed in the PR template checklist and enforced on review). Also dropped the now-redundant "including the CHANGELOG entry format" phrase from the Pull requests section since the dedicated section covers it. Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRIBUTING.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79869c38..cee9dd64 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,8 +71,7 @@ pytest -vv -s --doctest-modules 1. Push your branch and open a PR against `main`. 2. Fill in the [pull request template](.github/pull_request_template.md) - it contains the - full checklists for authors, reviewers, and assignees, including the - CHANGELOG entry format. + full checklists for authors, reviewers, and assignees. 3. Write commit messages in **imperative form** matching the existing `git log` style ("Add X" not "Added X"), and keep one concern per PR. 4. PRs land via **squash-and-merge**: the PR title becomes the single commit @@ -81,6 +80,27 @@ pytest -vv -s --doctest-modules preserved in `main`. 5. A maintainer will review your PR. Small, focused PRs are reviewed faster. +## CHANGELOG entries + +**Every PR must add a line to [CHANGELOG.md](CHANGELOG.md)** under the +section matching the change type (`Added`, `Changed`, `Fixed`, or +`Maintenance`). Add a new section heading if it does not already exist +under the current `[unreleased]` block. + +The entry references the **PR number, not the issue number**, and tags the +author. Format: + +```markdown +- Short description of the change [\#NNN](https://github.com/mllam/neural-lam/pull/NNN) @your-handle +``` + +Example (from a real merged PR): + +```markdown +- Add bounds checking for `--var_leads_metrics_watch` indices to fail at + CLI parse time rather than mid-validation [\#306](https://github.com/mllam/neural-lam/pull/306) @your-handle +``` + ## Monthly development meetings The mllam team meets monthly to coordinate roadmaps across the three core From a93682f0f4ab24051411a4dea9f96201b2aad61a Mon Sep 17 00:00:00 2001 From: sadamov Date: Tue, 9 Jun 2026 10:41:55 +0200 Subject: [PATCH 06/10] docs: address Joel's review on CONTRIBUTING.md Two inline review comments on PR #407 (mllam/neural-lam#407 review by @joeloskarsson): - L54: link to the numpydoc style guide as the authoritative external reference and point to `neural_lam/datastore/base.py` as a representative in-repo example of the conventions we follow. - L82: extend the Pull Requests numbered list with steps 6-7 covering what happens between first review and merge. Split bugfix / maintenance PRs (merged directly) from enhancement PRs (added to milestone as `proposed`, discussed at the dev meeting, moved to `confirmed`, merged when the milestone closes), making the link to the Monthly Dev Meetings section explicit. Co-Authored-By: Claude Opus 4.7 --- CONTRIBUTING.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cee9dd64..79b6b2fc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,7 +51,12 @@ Code quality is enforced automatically by Codespell and others). In addition: - Add **NumPy-style docstrings** and **type annotations** to every public - function and class. + function and class. The + [numpydoc style guide](https://numpydoc.readthedocs.io/en/latest/format.html) + is the authoritative reference; + [`neural_lam/datastore/base.py`](neural_lam/datastore/base.py) is a good + in-repo example of the conventions we follow (sectioned `Parameters` / + `Returns`, types in the signature line, prose first). - Keep new code consistent with the patterns already in the codebase. ## Before you push @@ -79,6 +84,17 @@ pytest -vv -s --doctest-modules before requesting review - per-commit history on your branch is not preserved in `main`. 5. A maintainer will review your PR. Small, focused PRs are reviewed faster. +6. After review, iterate on the feedback. Once the review is resolved and + CI is green: + - **Bugfixes and maintenance PRs** are merged directly by the assignee. + - **Feature PRs** (anything labelled `enhancement`) are added to the + next release milestone as **proposed**, then discussed at the next + [monthly dev meeting](#monthly-development-meetings) so the team can + align on roadmap and scope. Once the team confirms the PR for the + release, the milestone is updated to **confirmed**. +7. **Confirmed feature PRs** are merged when the milestone closes (or + sooner if the feature is self-contained and the maintainers agree). + Bugfix and maintenance PRs are merged as soon as step 6 completes. ## CHANGELOG entries From 16e77a3f20c08d1bf7df7b0e3355c856b9529200 Mon Sep 17 00:00:00 2001 From: Ananya542 Date: Tue, 28 Apr 2026 09:59:16 +0530 Subject: [PATCH 07/10] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20ad?= =?UTF-8?q?d=20CHANGELOG=20entry=20and=20fix=20Slack=20URL?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add CONTRIBUTING.md entry to CHANGELOG.md under [unreleased] ### Maintenance - Replace long Slack invite URL with stable short URL (kutt.to/mllam) Co-authored-by Claude Sonnet --- CONTRIBUTING.md | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79b6b2fc..a6f0e885 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,6 +71,28 @@ pytest -vv -s --doctest-modules > **Note:** The first test run downloads ~50 MB of example data via > [pooch](https://www.fatiando.org/pooch/). +## Community roadmap + +Our community roadmap is defined by +[milestones](https://github.com/mllam/neural-lam/milestones) on the +[`neural-lam` GitHub repo](https://github.com/mllam/neural-lam). We use +[semantic versioning](https://semver.org/) `vX.Y.Z` for the milestones, so +issues on the roadmap carry the version they will be part of as their +milestone. + +The process for putting issues or PRs on the roadmap is: + +1. **Propose** — label your issue or PR with a milestone in the form + `vX.Y.Z (proposed)` (e.g. `v0.9.2 (proposed)`). +2. **Discuss** — at a development meeting the assignee explains the purpose + and how it fits the current roadmap. The group decides whether to accept + it and which revision it targets (it may be moved to a later release). +3. **Accept** — once accepted the `(proposed)` suffix is removed and the + issue or PR is placed on the milestone for that version. + +To propose something for the roadmap, all you need to do is add a milestone +label in the form `vX.Y.Z (proposed)`. + ## Pull requests 1. Push your branch and open a PR against `main`. @@ -87,12 +109,14 @@ pytest -vv -s --doctest-modules 6. After review, iterate on the feedback. Once the review is resolved and CI is green: - **Bugfixes and maintenance PRs** are merged directly by the assignee. - - **Feature PRs** (anything labelled `enhancement`) are added to the - next release milestone as **proposed**, then discussed at the next + - **Feature PRs** (anything labelled `enhancement`) are proposed for the + [community roadmap](#community-roadmap) by adding a `vX.Y.Z (proposed)` + milestone, then discussed at the next [monthly dev meeting](#monthly-development-meetings) so the team can - align on roadmap and scope. Once the team confirms the PR for the - release, the milestone is updated to **confirmed**. -7. **Confirmed feature PRs** are merged when the milestone closes (or + align on roadmap and scope. Feature PRs accepted for the roadmap + (i.e. assigned a `vX.Y.Z` milestone without `(proposed)`) are merged + by the assignee once the milestone is ready. +7. **Accepted feature PRs** are merged when the milestone closes (or sooner if the feature is self-contained and the maintainers agree). Bugfix and maintenance PRs are merged as soon as step 6 completes. From b6e3cb16335eea78941118bf55825bf75d210cb7 Mon Sep 17 00:00:00 2001 From: sadamov Date: Thu, 11 Jun 2026 06:09:11 +0200 Subject: [PATCH 08/10] docs: use plain hyphen in CONTRIBUTING.md community roadmap bullets Match the rest of the file's punctuation style. Co-Authored-By: Claude Opus 4.7 --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a6f0e885..c9a2d6b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,12 +82,12 @@ milestone. The process for putting issues or PRs on the roadmap is: -1. **Propose** — label your issue or PR with a milestone in the form +1. **Propose** - label your issue or PR with a milestone in the form `vX.Y.Z (proposed)` (e.g. `v0.9.2 (proposed)`). -2. **Discuss** — at a development meeting the assignee explains the purpose +2. **Discuss** - at a development meeting the assignee explains the purpose and how it fits the current roadmap. The group decides whether to accept it and which revision it targets (it may be moved to a later release). -3. **Accept** — once accepted the `(proposed)` suffix is removed and the +3. **Accept** - once accepted the `(proposed)` suffix is removed and the issue or PR is placed on the milestone for that version. To propose something for the roadmap, all you need to do is add a milestone From 2363ce238ebbc70b052a814cb006efc4c9a58ae7 Mon Sep 17 00:00:00 2001 From: sadamov Date: Fri, 12 Jun 2026 09:55:52 +0200 Subject: [PATCH 09/10] add missing text in agents.md --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4285f45f..59b95056 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,7 +60,8 @@ repeat a question already answered or an approach already rejected. ### Commits -AI attribution is mandatory. Add a `Co-authored-by:` trailer to every commit produced with AI -assistance, e.g.: +AI attribution is mandatory. Add a `Co-authored-by:` trailer to every commit produced with AI assistance, e.g. `Co-authored-by: Claude Opus 4.8 `. + +### Changelog Every PR must add a line to `CHANGELOG.md` in the section matching the change type (`Added` / `Changed` / `Fixed` / `Maintenance`). From 75631577e86adb459ac85046c97106bd4616398b Mon Sep 17 00:00:00 2001 From: sadamov Date: Fri, 12 Jun 2026 09:56:20 +0200 Subject: [PATCH 10/10] add reference to tensor shape names in README --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c9a2d6b7..95ef4721 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,6 +57,9 @@ Codespell and others). In addition: [`neural_lam/datastore/base.py`](neural_lam/datastore/base.py) is a good in-repo example of the conventions we follow (sectioned `Parameters` / `Returns`, types in the signature line, prose first). +- When annotating tensor shapes, use the canonical dimension names from the + [Dimension Glossary](README.md#dimension-glossary) so shapes stay consistent + across the codebase. - Keep new code consistent with the patterns already in the codebase. ## Before you push