docs: add CONTRIBUTING.md and trims the AGENTS.md file using pointers by ANANYA542 · Pull Request #407 · mllam/neural-lam

ANANYA542 · 2026-03-16T18:36:49Z

Describe your changes

Adds docs/contributing/contributing.md — a concise contributor guide that walks a new contributor through the full workflow from fork to merged PR.
Covers: ways to contribute, environment setup (referencing existing README install instructions rather than duplicating them), all 13 pre-commit hooks documented, code standards, how to run the test suite locally using the exact CI commands, PR checklist, review process with CHANGELOG format, and a troubleshooting table.
The goal is to give new contributors a single document to reference rather than piecing together information from the README, PR template, and CI config separately. Redundant sections have been removed and replaced with direct references to existing docs.

UPDATE: The AGENTS.md file will be trimmed to avoid duplications.

Issue Link

fixes #406

Type of change

🐛 Bug fix (non-breaking change that fixes an issue)
✨ New feature (non-breaking change that adds functionality)
💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
📖 Documentation (Addition or improvements to documentation)

Checklist before requesting a review

My branch is up-to-date with the target branch - if not update your fork with the changes from the target branch (use pull with --rebase option if possible).
[X ] I have performed a self-review of my code
For any new/modified functions/classes I have added docstrings that clearly describe its purpose, expected inputs and returned values
I have placed in-line comments to clarify the intent of any hard-to-understand passages of my code
I have updated the README to cover introduced code changes
I have added tests that prove my fix is effective or that my feature works
I have given the PR a name that clearly describes the change, written in imperative form (context).
I have requested a reviewer and an assignee (assignee is responsible for merging). This applies only if you have write access to the repo, otherwise feel free to tag a maintainer to add a reviewer and assignee.

Checklist for reviewers

Each PR comes with its own improvements and flaws. The reviewer should check the following:

the code is readable
the code is well tested
the code is documented (including return types and parameters)
the code is easy to maintain

Author checklist after completed review

I have added a line to the CHANGELOG describing this change, in a section
reflecting type of change (add section where missing):
- added: when you have added new functionality
- changed: when default behaviour of the code has been changed
- fixes: when your contribution fixes a bug
- maintenance: when your contribution is relates to repo maintenance, e.g. CI/CD or documentation

Checklist for assignee

PR is up to date with the base branch
the tests pass
(if the PR is not just maintenance/bugfix) the PR is assigned to the next milestone. If it is not, propose it for a future milestone.
author has added an entry to the changelog (and designated the change as added, changed, fixed or maintenance)
Once the PR is ready to be merged, squash commits and merge the PR.

@joeloskarsson

…R template - Move from docs/contributing/contributing.md to repo root CONTRIBUTING.md - Replace full setup instructions with link to README - Replace PR checklists with link to PR template - Replace hook enumeration with link to .pre-commit-config.yaml - Remove troubleshooting table and maintainer tags - Add issue-first workflow and 'read discussion' step - Keep only the two essential verify commands Addresses feedback from @joeloskarsson on mllam#407

sadamov · 2026-03-31T06:21:12Z

@ANANYA542 I saw that you are expanding our work on this PR here. Note that autodoc is already tackled by #322. So I would prefer if this PR here could focus on the CONTRIBUTING.md file. And work closely together with #516 to reduce duplicated information that's hard to maintain. Could you reduce the scope of this PR here and update the title to make it clearer?

@joeloskarsson

…R template - Move from docs/contributing/contributing.md to repo root CONTRIBUTING.md - Replace full setup instructions with link to README - Replace PR checklists with link to PR template - Replace hook enumeration with link to .pre-commit-config.yaml - Remove troubleshooting table and maintainer tags - Add issue-first workflow and 'read discussion' step - Keep only the two essential verify commands Addresses feedback from @joeloskarsson on mllam#407

ANANYA542 · 2026-04-02T09:29:29Z

@sadamov Thanks for the review! I have dropped the Jupyter Book commits since #322 already tackles autodoc, and reduced the scope to focus solely on CONTRIBUTING.md at the root. This is ready and provides the complete contribution guidelines so that the subsequent #516 PR can heavily trim AGENTS.md to just link to this file. I updated the PR title as well.

@ANANYA542

Re-applies @ANANYA542's PR mllam#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 <ANANYA542@users.noreply.github.com> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@ANANYA542

Re-applies @ANANYA542's PR mllam#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 <ANANYA542@users.noreply.github.com> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

sadamov

I like this as a first version of our CONTRIBUTING guide. Should be aligned with AGENTS.md in the future. Let's discuss at the next dev-meeting how to proceed. thanks @ANANYA542 !

Resolved CHANGELOG conflict by keeping both the mllam#407 and mllam#266 maintenance entries (sequential, no overlap). Extended CONTRIBUTING.md with two new sections requested by the team: - A Community section up top covering the friendly, open-minded culture we want to maintain - assume good intent, ask questions early, credit each other, beginners welcome. - A Monthly development meetings section pointing at the second-Monday 10:00-11:00 CEST slot and the mllam Slack #general channel where the Zoom link is pinned. Frames the meeting as the right venue for cross-repo roadmap discussions across neural-lam, weather-model-graphs, and mllam-data-prep. Also refined the Getting help section so the two existing channels (Slack vs GitHub issues) read with a one-line "when to use which". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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-mllam#208 ForecasterModule / Forecaster / StepPredictor hierarchy, and added `pytest -m "not slow"` to the command list (per mllam#651). Net: 91 lines (down from 97), but the AI-specific content is denser. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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) <noreply@anthropic.com>

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-mllam#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) <noreply@anthropic.com>

sadamov · 2026-06-08T19:21:31Z

@ANANYA542 thanks for the patience on this one. I pushed a few additions on top of your work while we had this open, since the team wanted to fold in some bits at the same time. Your original CONTRIBUTING.md is still the spine of the document, everything I added layered on top. Let me know if anything should be different before I merge.

Per Copilot's review on mllam#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) <noreply@anthropic.com>

ANANYA542 · 2026-06-09T02:50:45Z

@sadamov Thanks for pushing this through and for all the additions while it was open. I had a look through the latest changes and everything looks good to me. Happy with where it ended up, so no further comments from my side. Appreciate all the work on this one!

joeloskarsson · 2026-06-09T06:50:47Z

Added a couple ideas above for improving clarity surrounding our processes. Overall I think this is very good 😄

@joeloskarsson

Two inline review comments on PR mllam#407 (mllam#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 <noreply@anthropic.com>

leifdenby

Really nice work! I only have one suggestion and that is to make our community roadmap process more explicit by putting it into a separate section and defining how we denote that a feature PR has been proposed to be put on the roadmap and how we denote that it has been accepted for the roadmap.

- 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 <claude@anthropic.com>

Match the rest of the file's punctuation style. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

This was referenced Mar 21, 2026

Add CONTRIBUTING.md with setup and contribution guidelines #451

Closed

Add CONTRIBUTING.md with setup and contribution guidelines #450

Closed

kshirajahere mentioned this pull request Mar 21, 2026

Add CONTRIBUTING.md to guide new contributors #477

Closed

sadamov mentioned this pull request Mar 25, 2026

Split the AGENTS.md file into separate self-contained files #516

Open

codedbyasim mentioned this pull request Mar 28, 2026

refactor: split AGENTS.md into separate self-contained files (#516) #531

Closed

sadamov mentioned this pull request Mar 31, 2026

Fix feature coordinate handling in WeatherDataset #558

Closed

21 tasks

ANANYA542 force-pushed the docs/contributing-guide branch from 48462b1 to cecbf9f Compare April 2, 2026 09:28

ANANYA542 changed the title ~~Docs/contributing guide~~ docs: add CONTRIBUTING.md Apr 2, 2026

sadamov added the documentation Improvements or additions to documentation label Apr 13, 2026

sadamov self-assigned this Apr 13, 2026

sadamov self-requested a review April 17, 2026 19:33

This comment was marked as spam.

Sign in to view

sadamov force-pushed the docs/contributing-guide branch from c3161ba to 15a3ebf Compare June 6, 2026 19:46

sadamov added this to the v0.7.0 (proposed) milestone Jun 6, 2026

sadamov force-pushed the docs/contributing-guide branch from 0111c8a to 7d60328 Compare June 6, 2026 19:58

sadamov approved these changes Jun 6, 2026

View reviewed changes

sadamov mentioned this pull request Jun 6, 2026

Improve development environment setup instructions #262

Closed

sadamov added the ready Review complete - proposed for milestone label Jun 6, 2026

sadamov mentioned this pull request Jun 6, 2026

Improve development environment setup instructions #261

Closed

joeloskarsson modified the milestones: v0.7.0 (proposed), v0.7.0 Jun 8, 2026

sadamov mentioned this pull request Jun 8, 2026

Probabilistic metrics & ensemble plumbing - consolidated track for v0.8.0 #649

Open

sadamov and others added 2 commits June 8, 2026 20:55

sadamov requested a review from Copilot June 8, 2026 19:11

Copilot started reviewing on behalf of sadamov June 8, 2026 19:11 View session

This comment was marked as spam.

Sign in to view

sadamov mentioned this pull request Jun 8, 2026

Add markdown link check + PR template doc-update reminder to keep CONTRIBUTING/AGENTS from rotting #654

Open

sadamov changed the title ~~docs: add CONTRIBUTING.md~~ docs: add CONTRIBUTING.md and trims the AGENTS.md file using pointers Jun 8, 2026

joeloskarsson reviewed Jun 9, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

joeloskarsson reviewed Jun 9, 2026

View reviewed changes

Comment thread CONTRIBUTING.md

sadamov and others added 2 commits June 9, 2026 10:41

Merge branch 'main' into docs/contributing-guide

22e287f

leifdenby requested changes Jun 9, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

Comment thread CONTRIBUTING.md Outdated

Comment thread CONTRIBUTING.md

ANANYA542 added 2 commits June 10, 2026 19:01

docs: address review — add CHANGELOG entry and fix Slack URL

16e77a3

- 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 <claude@anthropic.com>

Merge branch 'main' into docs/contributing-guide

6cb7986

sadamov requested a review from leifdenby June 11, 2026 04:08

docs: use plain hyphen in CONTRIBUTING.md community roadmap bullets

b6e3cb1

Match the rest of the file's punctuation style. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add CONTRIBUTING.md and trims the AGENTS.md file using pointers#407

docs: add CONTRIBUTING.md and trims the AGENTS.md file using pointers#407
ANANYA542 wants to merge 11 commits into
mllam:mainfrom
ANANYA542:docs/contributing-guide

ANANYA542 commented Mar 16, 2026 •

edited by sadamov

Loading

Uh oh!

sadamov commented Mar 31, 2026

Uh oh!

ANANYA542 commented Apr 2, 2026

Uh oh!

This comment was marked as spam.

Uh oh!

sadamov left a comment •

edited

Loading

Uh oh!

This comment was marked as spam.

Uh oh!

sadamov commented Jun 8, 2026

Uh oh!

ANANYA542 commented Jun 9, 2026

Uh oh!

Uh oh!

Uh oh!

joeloskarsson commented Jun 9, 2026

Uh oh!

leifdenby left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

ANANYA542 commented Mar 16, 2026 • edited by sadamov Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Describe your changes

Issue Link

Type of change

Checklist before requesting a review

Checklist for reviewers

Author checklist after completed review

Checklist for assignee

Uh oh!

sadamov commented Mar 31, 2026

Uh oh!

ANANYA542 commented Apr 2, 2026

Uh oh!

This comment was marked as spam.

Uh oh!

sadamov left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as spam.

Uh oh!

sadamov commented Jun 8, 2026

Uh oh!

ANANYA542 commented Jun 9, 2026

Uh oh!

Uh oh!

Uh oh!

joeloskarsson commented Jun 9, 2026

Uh oh!

leifdenby left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ANANYA542 commented Mar 16, 2026 •

edited by sadamov

Loading

sadamov left a comment •

edited

Loading