From 3d89474764732d401102b447be255046b7660482 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Thu, 8 Oct 2026 11:28:54 +0200 Subject: [PATCH 1/2] Add update instructions to the README and getting started Releases are coming often while experiments are still being added, so modelers need to know how to update an existing environment. The README and getting started page now show the update command, and both they and the installation page say to update before checking a submission and show --version to confirm the new release. Co-Authored-By: Claude Opus 5.5 (1M context) --- README.md | 11 +++++++++++ docs/getting-started.md | 10 +++++++++- docs/user/installation.md | 4 ++++ 3 files changed, 24 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b847d46..d938008 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,17 @@ used as submitted. A **warning** means it is usable but departs from what was asked for. Only errors make the command exit non-zero, so it can be run from a script. +## Update + +New releases come often while experiments are still being added. Update +before you check a submission: + +```bash +conda activate isschecker +conda update -c conda-forge isschecker +ismip7-compliance-checker --version +``` + ## Where to read more | | | diff --git a/docs/getting-started.md b/docs/getting-started.md index a5210bf..0ed2a89 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -14,7 +14,15 @@ do not mix. You get two commands: `ismip7-compliance-checker`, the checker, and `ismip7-generate-test-files`, which writes synthetic files the checker passes. -{doc}`user/installation` covers updating and installing from source. + +If you installed the checker earlier, update it before you check a submission: + +```bash +conda activate isschecker +conda update -c conda-forge isschecker +``` + +{doc}`user/installation` has more on updating, and on installing from source. ## Lay out your files diff --git a/docs/user/installation.md b/docs/user/installation.md index 6e96b7e..b11b08e 100644 --- a/docs/user/installation.md +++ b/docs/user/installation.md @@ -22,9 +22,13 @@ can be run from any directory. ## Updating +New releases come often while experiments are still being added. Update +before you check a submission: + ```bash conda activate isschecker conda update -c conda-forge isschecker +ismip7-compliance-checker --version ``` The conda-forge package is built from tagged releases, so it can be a release From 3471b8f8ea9fc8923725f45293fcea5910722d72 Mon Sep 17 00:00:00 2001 From: Xylar Asay-Davis Date: Mon, 12 Oct 2026 18:26:19 +0200 Subject: [PATCH 2/2] Move agent instructions to AGENTS.md AGENTS.md is read by agents other than Claude Code. CLAUDE.md now just imports it. Co-Authored-By: Claude Opus 5.5 (1M context) --- AGENTS.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 76 +------------------------------------------------------ 2 files changed, 77 insertions(+), 75 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..469b82d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,76 @@ +# ISM_SimulationChecker agent instructions + +These instructions apply to the whole repository. + +## GitHub pull requests and issues + +- Do not hard-wrap. Write each paragraph and each bullet as a single + line, however long. GitHub wraps them for display, and hard breaks + make later edits show up as reflowed paragraphs in the diff. +- Start with a paragraph summarizing what the pull request or issue is + about, then use sections for the detail. +- Use closing keywords for any issue the pull request fixes. +- Do not list individual commits in a pull request description. The + commits are already on the pull request; describe what the change + accomplishes as a whole instead. +- Do not describe testing in a pull request description. Testing goes + in its own `Testing` comment on the pull request. +- Drafts of descriptions, comments and plans are not repository + content. Never commit one. +- An issue should say what happens, what was expected instead, and + enough to reproduce it: the checker version, the command, and the log + lines or the file it was run on. + +## Writing for human readers + +These rules apply to anything a colleague reads: GitHub comments, pull +request descriptions, issues, plans. Not code comments or commit +messages, where a reader who wants the mechanism is already in the right +place. Per-artifact rules and worked examples are in +`.claude/skills//SKILL.md`, as plain markdown. Claude Code +loads the matching one automatically; other agents should read the +matching file before writing that artifact. + +There are two readerships. GitHub prose is read by the checker's +maintainers: developers who know the code's structure and the ISMIP7 +data request at a high level. The user documentation, the `--help` +strings and the checker's messages are read by modelers preparing a +submission, who never read the code and may not have English as a first +language. The `user-docs` skill has the rules for them. + +Never repeat explanations of existing, unchanged features already +explained in `docs`; link to the relevant page instead. Explanations are +appropriate where there is a change, particularly one of a conceptual +nature, and to highlight nuance that informs the current discussion. + +Write less; do not pack the same content into denser sentences. Keep +headings, tables and links. Colleagues mostly write unstructured prose, +and structure is an improvement on it. The problem is length. + +- **Lead with the answer.** The first two sentences say what you found, + changed, or propose. Setup and reproduction go last. +- **One point per paragraph, and few paragraphs.** Colleagues here write + one to three per comment; agent-written descriptions have run to two + thousand words. That gap is the complaint. Say each thing once. +- **Do not narrate the mechanism.** The chain of calls, and why the fix + is right, go in the commit message. Here, say what broke and where to + look. +- **Cut clauses that qualify rather than inform**, and any sentence whose + only job is to justify the one before it. One clause per sentence where + one will do. +- **Use backticks about half as often as feels natural.** They are for + what a reader would type or grep. Code blocks hold artifacts you did + not write, never authored prose. +- **One document, one decision.** Anything still relevant after this + merges is an issue, not a comment. + +Sign anything posted to GitHub on someone's behalf: + +``` +--- + +*Posted by on @'s behalf. The testing, analysis and wording +above are AI-authored; please check them accordingly.* +``` + +Name the agent, not the vendor: `Claude Code`, `Codex`, and so on. diff --git a/CLAUDE.md b/CLAUDE.md index db220c8..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,75 +1 @@ -# ISM_SimulationChecker agent instructions - -These instructions apply to the whole repository. - -## GitHub pull requests and issues - -- Do not hard-wrap. Write each paragraph and each bullet as a single - line, however long. GitHub wraps them for display, and hard breaks - make later edits show up as reflowed paragraphs in the diff. -- Start with a paragraph summarizing what the pull request or issue is - about, then use sections for the detail. -- Use closing keywords for any issue the pull request fixes. -- Do not list individual commits in a pull request description. The - commits are already on the pull request; describe what the change - accomplishes as a whole instead. -- Do not describe testing in a pull request description. Testing goes - in its own `Testing` comment on the pull request. -- Drafts of descriptions, comments and plans are not repository - content. Never commit one. -- An issue should say what happens, what was expected instead, and - enough to reproduce it: the checker version, the command, and the log - lines or the file it was run on. - -## Writing for human readers - -These rules apply to anything a colleague reads: GitHub comments, pull -request descriptions, issues, plans. Not code comments or commit -messages, where a reader who wants the mechanism is already in the right -place. Per-artifact rules and worked examples are in -`.claude/skills//SKILL.md`, as plain markdown; Claude Code -loads the matching one automatically. - -There are two readerships. GitHub prose is read by the checker's -maintainers: developers who know the code's structure and the ISMIP7 -data request at a high level. The user documentation, the `--help` -strings and the checker's messages are read by modelers preparing a -submission, who never read the code and may not have English as a first -language. The `user-docs` skill has the rules for them. - -Never repeat explanations of existing, unchanged features already -explained in `docs`; link to the relevant page instead. Explanations are -appropriate where there is a change, particularly one of a conceptual -nature, and to highlight nuance that informs the current discussion. - -Write less; do not pack the same content into denser sentences. Keep -headings, tables and links. Colleagues mostly write unstructured prose, -and structure is an improvement on it. The problem is length. - -- **Lead with the answer.** The first two sentences say what you found, - changed, or propose. Setup and reproduction go last. -- **One point per paragraph, and few paragraphs.** Colleagues here write - one to three per comment; agent-written descriptions have run to two - thousand words. That gap is the complaint. Say each thing once. -- **Do not narrate the mechanism.** The chain of calls, and why the fix - is right, go in the commit message. Here, say what broke and where to - look. -- **Cut clauses that qualify rather than inform**, and any sentence whose - only job is to justify the one before it. One clause per sentence where - one will do. -- **Use backticks about half as often as feels natural.** They are for - what a reader would type or grep. Code blocks hold artifacts you did - not write, never authored prose. -- **One document, one decision.** Anything still relevant after this - merges is an issue, not a comment. - -Sign anything posted to GitHub on someone's behalf: - -``` ---- - -*Posted by on @'s behalf. The testing, analysis and wording -above are AI-authored; please check them accordingly.* -``` - -Name the agent, not the vendor: `Claude Code`, `Codex`, and so on. +@AGENTS.md