From 25118f5155293c2d380a48df91af97d82c5caf06 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Tue, 27 Oct 2026 15:44:17 -0600 Subject: [PATCH 01/59] Add instructions for the use of AI coding tools New section in CONTRIBUTING.md and some GitHub templates; new AGENTS.md file. --- .github/ISSUE_TEMPLATE/01_bug_report.md | 9 ++++++++ .github/ISSUE_TEMPLATE/03_documentation.md | 9 ++++++++ .github/PULL_REQUEST_TEMPLATE.md | 9 ++++++++ AGENTS.md | 19 +++++++++++++++ CONTRIBUTING.md | 27 ++++++++++++++++++++++ 5 files changed, 73 insertions(+) create mode 100644 AGENTS.md diff --git a/.github/ISSUE_TEMPLATE/01_bug_report.md b/.github/ISSUE_TEMPLATE/01_bug_report.md index 427217bdfb..13b2278f32 100644 --- a/.github/ISSUE_TEMPLATE/01_bug_report.md +++ b/.github/ISSUE_TEMPLATE/01_bug_report.md @@ -16,6 +16,15 @@ about: Report a problem with the code **Configurations affected:** [Fill this in if known.] +### AI disclosure + +- [ ] Was AI used in this contribution? Yes/no: + +If yes: +- [ ] Types of work: +- Provider (optional): +- Model (optional): + ### Details of bug [Fill in details here.] diff --git a/.github/ISSUE_TEMPLATE/03_documentation.md b/.github/ISSUE_TEMPLATE/03_documentation.md index 5538f047a0..c606b7dbbb 100644 --- a/.github/ISSUE_TEMPLATE/03_documentation.md +++ b/.github/ISSUE_TEMPLATE/03_documentation.md @@ -22,3 +22,12 @@ A clear and concise description of what is missing or wrong. ### Additional context (optional) Add any other context or screenshots about the issue here. + +### AI disclosure + +- [ ] Was AI used in this contribution? **Yes/no** + +If yes: +- [ ] Types of work: +- Provider (optional): +- Model (optional): diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 6ef2db80b6..fd94f993e9 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -28,6 +28,15 @@ the list of common problems to watch out for - [ ] (Replace this text and add more list items as needed) +### AI disclosure + +- [ ] Was AI used in this contribution? **Yes or no** + +If yes: +- [ ] Types of work: +- Provider (optional): +- Model (optional): + ### Requirements before merge: diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..561e3612b7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,19 @@ +# AGENTS.md + +**Read and obey the standards described and linked in `CONTRIBUTING.md`.** + +## General rules +- You must assume that any development design or implementation plan documents will not be brought into the repository upon merge. It's fine to commit them, but the maintainers will remove them before merge. Therefore, all work you do -- code comments, persistent documentation, commit messages -- must stand on their own without reference to those documents. + +## Commits +- Commits must, as much as possible, do one "thing" and do it completely. It's fine for commits to work in multiple places across the codebase, but +- The "headline" of commit messages must, as much as possible, be written in plain language that can be understood by someone familiar with CTSM but not necessarily with the issue being addressed. +- No part of any commit message may reference development plan documents without at least explaining the referent. E.g., "Task 2 Step 4" is not acceptable without saying what that *is* (e.g., "Separate xyz functionality into a separate subroutine). Ideally, though, such references would be stripped by rebasing before requesting review on a PR. +- Commit messages that you as an LLM write must include a "Co-Authored By" credit naming your model provider and version. This also applies to messages a human writes for commits containing *material* that you wrote -- make sure the human complies, or ask to amend commits to add it as necessary. + +## GitHub issues and pull requests + +- When asked to open a PR or create an issue, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. +- If asked to draft an issue or PR, follow the repository templates: `.github/pull_request_template.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. +- Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. +- **You may never submit or contribute to an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI usage" disclosure to keep it accurate as the issue or PR evolves. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a0a98d507e..83259494e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,10 +27,37 @@ This also allows your changes to be planned for and slated for a time to come in cases you won't merge the Pull Request yourself, but a software engineer responsible for CTSM will do additional testing and bring the changes to CTSM master. +Please keep pull requests focused and small enough for the very busy maintainers to understand and review. + ### CTSM Developers Guide: https://wiki.ucar.edu/display/ccsm/Community+Land+Model+Developers+Guide +## AI Usage Policies + +AI tools make it very easy to find apparent issues and submit suggested changes. If what you have found is not already an issue in this repo, we **strongly recommend** opening an issue or discussion here, as described at the top of this document. + +We permit generative AI assistance, but responsibility remains with people. AI assistance must not shift the work of understanding, debugging, or validating a contribution onto maintainers. The same quality, licensing, and reproducibility standards apply whether or not AI is used. + +In this policy, "you" refers to the human contributor. AI tools assisting with a contribution should direct their human operator to this policy and remind them to personally review and understand an issue before submission, or the complete set of changes in a PR before requesting review. An AI tool must not claim that the operator has done so unless the operator confirms it. + +Before requesting review on a PR, personally review and understand the complete set of changes in the PR, whether or not AI was used. This includes code, tests, configuration, documentation, and generated files. If your PR does not yet satisfy this requirement, leave it as a draft. + +You must be able to explain why the changes are correct, how they fit CTSM, and how they were validated. AI review and passing automated checks do not replace human understanding or project review. You remain responsible for your contribution and for personally addressing review feedback. + +**Do not submit unreviewed AI output to this repository.** Issue and PR descriptions, comments, and review responses must reflect your own reasoning and understanding. Translation, grammar, and phrasing assistance are welcome, provided you verify the meaning. + +**Do not delegate conversations with maintainers to an agent.** The maintainers of this repo are human beings who will use their human brains to review every single line of your contribution. Please show them the same courtesy when discussing an issue or PR. + +Every issue and PR must state whether generative AI was used in preparing the contribution, including research, code, tests, documentation, or language assistance. If AI was used, briefly describe how it was used; this description is required. Provider and model are optional. Keep the disclosure current as the PR changes, even if generated material was subsequently rewritten. Ordinary formatters, compilers, and test runners do not require AI disclosure. For example: +> AI used: Yes +> Usage: Suggested XML parsing tests and helped edit documentation. +> Provider (optional): Anthropic +> Model (optional): Claude Opus 5.5 (extra-high effort) + +Further instructions can be found in `AGENTS.md`. + + ## Getting Started: The following resources give you information on the project and how to get started. From b9437652f33df492f63e102f64d62ccaaf26a7c7 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 12:18:11 -0600 Subject: [PATCH 02/59] AGENTS.md: Fix case of a path. --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 561e3612b7..2c54632d23 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,6 @@ ## GitHub issues and pull requests - When asked to open a PR or create an issue, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. -- If asked to draft an issue or PR, follow the repository templates: `.github/pull_request_template.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. +- If asked to draft an issue or PR, follow the repository templates: `.github/PULL_REQUEST_TEMPLATE.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. - **You may never submit or contribute to an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI usage" disclosure to keep it accurate as the issue or PR evolves. From d822d27e3fbf315b21d052a8d59a20c87b77eb80 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 12:23:51 -0600 Subject: [PATCH 03/59] AGENTS.md: Clarify: Allowed to draft issues/PRs but not touch them. (Except for keeping the AI Disclosure field up-to-date.) --- AGENTS.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2c54632d23..62c46b1275 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -**Read and obey the standards described and linked in `CONTRIBUTING.md`.** +**Read and obey all standards described and linked in `CONTRIBUTING.md`.** ## General rules - You must assume that any development design or implementation plan documents will not be brought into the repository upon merge. It's fine to commit them, but the maintainers will remove them before merge. Therefore, all work you do -- code comments, persistent documentation, commit messages -- must stand on their own without reference to those documents. @@ -13,7 +13,6 @@ ## GitHub issues and pull requests -- When asked to open a PR or create an issue, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. -- If asked to draft an issue or PR, follow the repository templates: `.github/PULL_REQUEST_TEMPLATE.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. +- **You may never submit or contribute to an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI usage" disclosure section to keep it accurate as the issue or PR evolves. +- You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. Then follow the repository templates: `.github/PULL_REQUEST_TEMPLATE.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. -- **You may never submit or contribute to an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI usage" disclosure to keep it accurate as the issue or PR evolves. From edb2bc51a2ab2e55ba5ca6bde6860436214025d7 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 12:26:37 -0600 Subject: [PATCH 04/59] AGENTS.md: Prompt human to keep description updated. --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 62c46b1275..22db515b89 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,4 +15,5 @@ - **You may never submit or contribute to an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI usage" disclosure section to keep it accurate as the issue or PR evolves. - You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. Then follow the repository templates: `.github/PULL_REQUEST_TEMPLATE.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. +- You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. This is important: Prompt your human to keep the description up to date as the issue or PR evolves. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. From f962503456def15be02ebc3a404ad084a3863ce7 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 12:29:43 -0600 Subject: [PATCH 05/59] AI disclosure section now consistent throughout repo. Across all templates and CONTRIBUTING.md. Also added "Brief summary" and "Further details" sections to science discussion and other templates, which had no sections. --- .github/ISSUE_TEMPLATE/01_bug_report.md | 2 +- .github/ISSUE_TEMPLATE/02_science_discussion.md | 11 +++++++++++ .github/ISSUE_TEMPLATE/03_documentation.md | 4 ++-- .github/ISSUE_TEMPLATE/04_other.md | 11 +++++++++++ CONTRIBUTING.md | 10 ++++++---- 5 files changed, 31 insertions(+), 7 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/01_bug_report.md b/.github/ISSUE_TEMPLATE/01_bug_report.md index 13b2278f32..97cd5ea892 100644 --- a/.github/ISSUE_TEMPLATE/01_bug_report.md +++ b/.github/ISSUE_TEMPLATE/01_bug_report.md @@ -18,7 +18,7 @@ about: Report a problem with the code ### AI disclosure -- [ ] Was AI used in this contribution? Yes/no: +- [ ] Was AI used in this contribution? **Yes/no**: If yes: - [ ] Types of work: diff --git a/.github/ISSUE_TEMPLATE/02_science_discussion.md b/.github/ISSUE_TEMPLATE/02_science_discussion.md index 25f47ff601..439dbb2a62 100644 --- a/.github/ISSUE_TEMPLATE/02_science_discussion.md +++ b/.github/ISSUE_TEMPLATE/02_science_discussion.md @@ -4,4 +4,15 @@ about: We encourage the use of issues to discuss CTSM science developments --- +### Brief summary +### Further details + +### AI disclosure + +- [ ] Was AI used in this contribution? **Yes/no**: + +If yes: +- [ ] Types of work: +- Provider (optional): +- Model (optional): diff --git a/.github/ISSUE_TEMPLATE/03_documentation.md b/.github/ISSUE_TEMPLATE/03_documentation.md index c606b7dbbb..008de6784a 100644 --- a/.github/ISSUE_TEMPLATE/03_documentation.md +++ b/.github/ISSUE_TEMPLATE/03_documentation.md @@ -25,9 +25,9 @@ Add any other context or screenshots about the issue here. ### AI disclosure -- [ ] Was AI used in this contribution? **Yes/no** +- [ ] Was AI used in this contribution? **Yes/no**: If yes: -- [ ] Types of work: +- [ ] Types of work: - Provider (optional): - Model (optional): diff --git a/.github/ISSUE_TEMPLATE/04_other.md b/.github/ISSUE_TEMPLATE/04_other.md index f2cfcc7407..66f89703b6 100644 --- a/.github/ISSUE_TEMPLATE/04_other.md +++ b/.github/ISSUE_TEMPLATE/04_other.md @@ -4,4 +4,15 @@ about: Other issues (enhancement, cleanup, etc.) --- +### Brief summary +### Further details + +### AI disclosure + +- [ ] Was AI used in this contribution? **Yes/no**: + +If yes: +- [ ] Types of work: +- Provider (optional): +- Model (optional): diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 83259494e3..f95bc34f5f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,10 +50,12 @@ You must be able to explain why the changes are correct, how they fit CTSM, and **Do not delegate conversations with maintainers to an agent.** The maintainers of this repo are human beings who will use their human brains to review every single line of your contribution. Please show them the same courtesy when discussing an issue or PR. Every issue and PR must state whether generative AI was used in preparing the contribution, including research, code, tests, documentation, or language assistance. If AI was used, briefly describe how it was used; this description is required. Provider and model are optional. Keep the disclosure current as the PR changes, even if generated material was subsequently rewritten. Ordinary formatters, compilers, and test runners do not require AI disclosure. For example: -> AI used: Yes -> Usage: Suggested XML parsing tests and helped edit documentation. -> Provider (optional): Anthropic -> Model (optional): Claude Opus 5.5 (extra-high effort) + +> - [x] Was AI used in this contribution? **Yes**: +> If yes: +> - [x] Types of work: Designing changes, writing tests. +> - Provider (optional): Anthropic +> - Model (optional): Claude Opus 5.5 (extra-high effort) Further instructions can be found in `AGENTS.md`. From a21691fcef217c9543982cad0ca63eb2ce77b650 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 12:30:40 -0600 Subject: [PATCH 06/59] AGENTS.md: Clarify "contribute to" in GitHub section. --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 22db515b89..5d24e5bc71 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,7 @@ ## GitHub issues and pull requests -- **You may never submit or contribute to an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI usage" disclosure section to keep it accurate as the issue or PR evolves. +- **You may never submit, edit, comment on, or otherwise interact with an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI usage" disclosure section to keep it accurate as the issue or PR evolves. - You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. Then follow the repository templates: `.github/PULL_REQUEST_TEMPLATE.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. - You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. This is important: Prompt your human to keep the description up to date as the issue or PR evolves. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. From 45d4fe50a1c43075420644ca9bccc63dc066d7b1 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 12:32:08 -0600 Subject: [PATCH 07/59] AGENTS.md: Don't fetch EVERYTHING linked in CONTRIBUTING.md. --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 5d24e5bc71..47cfc53047 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -**Read and obey all standards described and linked in `CONTRIBUTING.md`.** +**Read and obey all standards described in `CONTRIBUTING.md`, including the webpage linked under "Coding Practices and Style."** ## General rules - You must assume that any development design or implementation plan documents will not be brought into the repository upon merge. It's fine to commit them, but the maintainers will remove them before merge. Therefore, all work you do -- code comments, persistent documentation, commit messages -- must stand on their own without reference to those documents. From 4dfbe59c05111eea3a960d56337fc303750c23af Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 12:34:40 -0600 Subject: [PATCH 08/59] AGENTS.md: Give example Co-Authored-By. --- AGENTS.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 47cfc53047..6fa74429a1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,10 @@ - Commits must, as much as possible, do one "thing" and do it completely. It's fine for commits to work in multiple places across the codebase, but - The "headline" of commit messages must, as much as possible, be written in plain language that can be understood by someone familiar with CTSM but not necessarily with the issue being addressed. - No part of any commit message may reference development plan documents without at least explaining the referent. E.g., "Task 2 Step 4" is not acceptable without saying what that *is* (e.g., "Separate xyz functionality into a separate subroutine). Ideally, though, such references would be stripped by rebasing before requesting review on a PR. -- Commit messages that you as an LLM write must include a "Co-Authored By" credit naming your model provider and version. This also applies to messages a human writes for commits containing *material* that you wrote -- make sure the human complies, or ask to amend commits to add it as necessary. +- Commit messages that you as an LLM write must include a "Co-Authored-By" credit at the end naming your model and version. This also applies to messages a human writes for commits containing *material* that you wrote -- make sure the human complies, or ask to amend commits to add it as necessary. For example: +``` +Co-Authored-By: Claude Opus 5.5 +``` ## GitHub issues and pull requests From 3fa84615aa9ff3672bc3ae68d41f0c713f9c0e2c Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 12:37:27 -0600 Subject: [PATCH 09/59] AGENTS.md: Clarify "The CTSM repo" means ESCOMP's. --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 6fa74429a1..ca6ac936e6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,6 +15,7 @@ Co-Authored-By: Claude Opus 5.5 ``` ## GitHub issues and pull requests +"The CTSM repo" in this section specifically refers to the GitHub repo ESCOMP/CTSM, not forks. - **You may never submit, edit, comment on, or otherwise interact with an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI usage" disclosure section to keep it accurate as the issue or PR evolves. - You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. Then follow the repository templates: `.github/PULL_REQUEST_TEMPLATE.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. From 63a3f8789d8496fc0320cebe7983ad4cdbbd989f Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 12:44:13 -0600 Subject: [PATCH 10/59] AGENTS.md: Finish a sentence --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index ca6ac936e6..1e7d33ff31 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ - You must assume that any development design or implementation plan documents will not be brought into the repository upon merge. It's fine to commit them, but the maintainers will remove them before merge. Therefore, all work you do -- code comments, persistent documentation, commit messages -- must stand on their own without reference to those documents. ## Commits -- Commits must, as much as possible, do one "thing" and do it completely. It's fine for commits to work in multiple places across the codebase, but +- Commits must, as much as possible, do one "thing" and do it completely. It's fine for commits to work in multiple places across the codebase, if this is necessary to perform one coherent step of development. - The "headline" of commit messages must, as much as possible, be written in plain language that can be understood by someone familiar with CTSM but not necessarily with the issue being addressed. - No part of any commit message may reference development plan documents without at least explaining the referent. E.g., "Task 2 Step 4" is not acceptable without saying what that *is* (e.g., "Separate xyz functionality into a separate subroutine). Ideally, though, such references would be stripped by rebasing before requesting review on a PR. - Commit messages that you as an LLM write must include a "Co-Authored-By" credit at the end naming your model and version. This also applies to messages a human writes for commits containing *material* that you wrote -- make sure the human complies, or ask to amend commits to add it as necessary. For example: From 803ab61be81d76a539386bb54496102914be1f00 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 12:54:19 -0600 Subject: [PATCH 11/59] AGENTS.md: More clarifications in GitHub section. --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1e7d33ff31..4b18b64761 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,8 @@ Co-Authored-By: Claude Opus 5.5 ## GitHub issues and pull requests "The CTSM repo" in this section specifically refers to the GitHub repo ESCOMP/CTSM, not forks. -- **You may never submit, edit, comment on, or otherwise interact with an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI usage" disclosure section to keep it accurate as the issue or PR evolves. +- **You may never submit, edit, or comment on an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI usage" disclosure section to keep it accurate as the issue or PR evolves. - You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. Then follow the repository templates: `.github/PULL_REQUEST_TEMPLATE.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. -- You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. This is important: Prompt your human to keep the description up to date as the issue or PR evolves. +- You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Prompt your human to keep the entire description up to date as the issue or PR evolves. Remember, you are not allowed to edit an issue or PR description except for the "AI usage" disclosure section. +- Unless your user tells you otherwise, you are also allowed to push to branches in forks, including branches that have associated PRs in ESCOMP/CTSM. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. From 7b6708cebceeca8d6c6dbe04bc45a1f637631860 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 12:57:01 -0600 Subject: [PATCH 12/59] Don't allow blank issues; force use of a template. --- .github/ISSUE_TEMPLATE/config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index e76b47bf4a..892562fa41 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,4 +1,4 @@ -blank_issues_enabled: true +blank_issues_enabled: false contact_links: - name: CESM forums url: https://bb.cgd.ucar.edu/cesm/forums/ctsm-clm-mosart-rtm.134/ From 1b47c4a355acd7128dbea0e243d7b8a2a60432b6 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 13:00:57 -0600 Subject: [PATCH 13/59] CONTRIBUTING.md: Clarify "assisting with a contribution." --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f95bc34f5f..47635a9033 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,7 +39,7 @@ AI tools make it very easy to find apparent issues and submit suggested changes. We permit generative AI assistance, but responsibility remains with people. AI assistance must not shift the work of understanding, debugging, or validating a contribution onto maintainers. The same quality, licensing, and reproducibility standards apply whether or not AI is used. -In this policy, "you" refers to the human contributor. AI tools assisting with a contribution should direct their human operator to this policy and remind them to personally review and understand an issue before submission, or the complete set of changes in a PR before requesting review. An AI tool must not claim that the operator has done so unless the operator confirms it. +In this policy, "you" refers to the human contributor. AI tools drafting an issue or PR (or whose humans say they will be opening one) should direct their human operator to this policy and remind them to personally review and understand an issue before submission, or the complete set of changes in a PR before requesting review. An AI tool must not claim that the operator has done so unless the operator confirms it. Before requesting review on a PR, personally review and understand the complete set of changes in the PR, whether or not AI was used. This includes code, tests, configuration, documentation, and generated files. If your PR does not yet satisfy this requirement, leave it as a draft. From e22579d2310eec20c2d8604bd2a2a4374094eb64 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 28 Oct 2026 13:04:14 -0600 Subject: [PATCH 14/59] AGENTS.md: Fix refs to AI disclosure section name. --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4b18b64761..127511a514 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,8 +17,8 @@ Co-Authored-By: Claude Opus 5.5 ## GitHub issues and pull requests "The CTSM repo" in this section specifically refers to the GitHub repo ESCOMP/CTSM, not forks. -- **You may never submit, edit, or comment on an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI usage" disclosure section to keep it accurate as the issue or PR evolves. +- **You may never submit, edit, or comment on an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI disclosure" section to keep it accurate as the issue or PR evolves. - You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. Then follow the repository templates: `.github/PULL_REQUEST_TEMPLATE.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. -- You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Prompt your human to keep the entire description up to date as the issue or PR evolves. Remember, you are not allowed to edit an issue or PR description except for the "AI usage" disclosure section. +- You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Prompt your human to keep the entire description up to date as the issue or PR evolves. Remember, you are not allowed to edit an issue or PR description except for the "AI disclosure" section. - Unless your user tells you otherwise, you are also allowed to push to branches in forks, including branches that have associated PRs in ESCOMP/CTSM. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. From 41ddc3dea379e4de57ce8ee034fd8f6803434ddf Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 11:02:55 -0600 Subject: [PATCH 15/59] GH templates: Add example AI usages --- .github/ISSUE_TEMPLATE/01_bug_report.md | 1 + .github/ISSUE_TEMPLATE/02_science_discussion.md | 1 + .github/ISSUE_TEMPLATE/03_documentation.md | 1 + .github/ISSUE_TEMPLATE/04_other.md | 1 + .github/PULL_REQUEST_TEMPLATE.md | 1 + 5 files changed, 5 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/01_bug_report.md b/.github/ISSUE_TEMPLATE/01_bug_report.md index 97cd5ea892..8f88525da5 100644 --- a/.github/ISSUE_TEMPLATE/01_bug_report.md +++ b/.github/ISSUE_TEMPLATE/01_bug_report.md @@ -21,6 +21,7 @@ about: Report a problem with the code - [ ] Was AI used in this contribution? **Yes/no**: If yes: + - [ ] Types of work: - Provider (optional): - Model (optional): diff --git a/.github/ISSUE_TEMPLATE/02_science_discussion.md b/.github/ISSUE_TEMPLATE/02_science_discussion.md index 439dbb2a62..15da0992f6 100644 --- a/.github/ISSUE_TEMPLATE/02_science_discussion.md +++ b/.github/ISSUE_TEMPLATE/02_science_discussion.md @@ -13,6 +13,7 @@ about: We encourage the use of issues to discuss CTSM science developments - [ ] Was AI used in this contribution? **Yes/no**: If yes: + - [ ] Types of work: - Provider (optional): - Model (optional): diff --git a/.github/ISSUE_TEMPLATE/03_documentation.md b/.github/ISSUE_TEMPLATE/03_documentation.md index 008de6784a..a76db1d1f6 100644 --- a/.github/ISSUE_TEMPLATE/03_documentation.md +++ b/.github/ISSUE_TEMPLATE/03_documentation.md @@ -28,6 +28,7 @@ Add any other context or screenshots about the issue here. - [ ] Was AI used in this contribution? **Yes/no**: If yes: + - [ ] Types of work: - Provider (optional): - Model (optional): diff --git a/.github/ISSUE_TEMPLATE/04_other.md b/.github/ISSUE_TEMPLATE/04_other.md index 66f89703b6..ef97d4ff43 100644 --- a/.github/ISSUE_TEMPLATE/04_other.md +++ b/.github/ISSUE_TEMPLATE/04_other.md @@ -13,6 +13,7 @@ about: Other issues (enhancement, cleanup, etc.) - [ ] Was AI used in this contribution? **Yes/no**: If yes: + - [ ] Types of work: - Provider (optional): - Model (optional): diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fd94f993e9..80fc9b8591 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -33,6 +33,7 @@ the list of common problems to watch out for - [ ] Was AI used in this contribution? **Yes or no** If yes: + - [ ] Types of work: - Provider (optional): - Model (optional): From 27f5a895c433e2d980e76dc680a1df2af033a226 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 11:05:08 -0600 Subject: [PATCH 16/59] Bug report template: Confirm it's real --- .github/ISSUE_TEMPLATE/01_bug_report.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/01_bug_report.md b/.github/ISSUE_TEMPLATE/01_bug_report.md index 8f88525da5..d14ec4324c 100644 --- a/.github/ISSUE_TEMPLATE/01_bug_report.md +++ b/.github/ISSUE_TEMPLATE/01_bug_report.md @@ -23,6 +23,8 @@ about: Report a problem with the code If yes: - [ ] Types of work: + +- [ ] I have confirmed that this is a real bug. **How:** - Provider (optional): - Model (optional): From 4de9ce9404b39072c1e67080f8ec3933fd22a690 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 11:09:15 -0600 Subject: [PATCH 17/59] CONTRIBUTING.md: Rework order of AI section --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47635a9033..dd020e1ad7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,12 +35,12 @@ Please keep pull requests focused and small enough for the very busy maintainers ## AI Usage Policies +In this policy, "you" refers to the human contributor. AI tools drafting an issue or PR (or whose humans say they will be opening one) should direct their human operator to this policy and remind them to personally review and understand an issue before submission, or the complete set of changes in a PR before requesting review. An AI tool must not claim that the operator has done so unless the operator confirms it. + AI tools make it very easy to find apparent issues and submit suggested changes. If what you have found is not already an issue in this repo, we **strongly recommend** opening an issue or discussion here, as described at the top of this document. We permit generative AI assistance, but responsibility remains with people. AI assistance must not shift the work of understanding, debugging, or validating a contribution onto maintainers. The same quality, licensing, and reproducibility standards apply whether or not AI is used. -In this policy, "you" refers to the human contributor. AI tools drafting an issue or PR (or whose humans say they will be opening one) should direct their human operator to this policy and remind them to personally review and understand an issue before submission, or the complete set of changes in a PR before requesting review. An AI tool must not claim that the operator has done so unless the operator confirms it. - Before requesting review on a PR, personally review and understand the complete set of changes in the PR, whether or not AI was used. This includes code, tests, configuration, documentation, and generated files. If your PR does not yet satisfy this requirement, leave it as a draft. You must be able to explain why the changes are correct, how they fit CTSM, and how they were validated. AI review and passing automated checks do not replace human understanding or project review. You remain responsible for your contribution and for personally addressing review feedback. From e8f23bfb551339412cea377bfaac37b7feda6370 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 11:16:03 -0600 Subject: [PATCH 18/59] CONTRIBUTING.md: Require issues first. --- CONTRIBUTING.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd020e1ad7..c970f325e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,9 @@ ## How to contribute: -We recommend that you first open an issue (https://github.com/escomp/ctsm/issues/) to +We appreciate that you want to contribute to making CTSM better! Before you submit a pull request, however, we require that you first open an issue (https://github.com/escomp/ctsm/issues/) to discuss the changes or additions that you propose. Through the issue discussion, you can work with other CTSM developers to think about the design and implementation of the changes -as well as the planning and scheduling for the change to come into CTSM. An alternative is -to contact the key software and science developers via ctsm-software@ucar.edu. Making +as well as the planning and scheduling for the change to come into CTSM. Making contact early in your project will increase the likelihood that your developments can come into CTSM. @@ -37,7 +36,7 @@ Please keep pull requests focused and small enough for the very busy maintainers In this policy, "you" refers to the human contributor. AI tools drafting an issue or PR (or whose humans say they will be opening one) should direct their human operator to this policy and remind them to personally review and understand an issue before submission, or the complete set of changes in a PR before requesting review. An AI tool must not claim that the operator has done so unless the operator confirms it. -AI tools make it very easy to find apparent issues and submit suggested changes. If what you have found is not already an issue in this repo, we **strongly recommend** opening an issue or discussion here, as described at the top of this document. +AI tools make it very easy to find apparent issues and submit suggested changes. If what you have found is not already an issue in this repo, you are required to open an issue or discussion here before submitting a pull request, as described at the top of this document. We permit generative AI assistance, but responsibility remains with people. AI assistance must not shift the work of understanding, debugging, or validating a contribution onto maintainers. The same quality, licensing, and reproducibility standards apply whether or not AI is used. From d8a85517825eaf8465f777f8a3b336df7dd5e496 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 11:16:38 -0600 Subject: [PATCH 19/59] AGENTS.md: reword, not amend --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 127511a514..07f1c50014 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ - Commits must, as much as possible, do one "thing" and do it completely. It's fine for commits to work in multiple places across the codebase, if this is necessary to perform one coherent step of development. - The "headline" of commit messages must, as much as possible, be written in plain language that can be understood by someone familiar with CTSM but not necessarily with the issue being addressed. - No part of any commit message may reference development plan documents without at least explaining the referent. E.g., "Task 2 Step 4" is not acceptable without saying what that *is* (e.g., "Separate xyz functionality into a separate subroutine). Ideally, though, such references would be stripped by rebasing before requesting review on a PR. -- Commit messages that you as an LLM write must include a "Co-Authored-By" credit at the end naming your model and version. This also applies to messages a human writes for commits containing *material* that you wrote -- make sure the human complies, or ask to amend commits to add it as necessary. For example: +- Commit messages that you as an LLM write must include a "Co-Authored-By" credit at the end naming your model and version. This also applies to messages a human writes for commits containing *material* that you wrote -- make sure the human complies, or ask to reword commits to add it as necessary. For example: ``` Co-Authored-By: Claude Opus 5.5 ``` From 91bba3bcd584cbbe20ead7ac39e584d4fde04492 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 11:19:22 -0600 Subject: [PATCH 20/59] AGENTS.md: Require *them* to remove planning docs --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 07f1c50014..749e33ca88 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,7 @@ **Read and obey all standards described in `CONTRIBUTING.md`, including the webpage linked under "Coding Practices and Style."** ## General rules -- You must assume that any development design or implementation plan documents will not be brought into the repository upon merge. It's fine to commit them, but the maintainers will remove them before merge. Therefore, all work you do -- code comments, persistent documentation, commit messages -- must stand on their own without reference to those documents. +- You must assume that any development design or implementation plan documents will not be brought into the repository upon merge. It's fine to commit them and even open pull requests with them present, but the maintainers will require that you remove them before merge. Therefore, all work you do -- code comments, persistent documentation, commit messages -- must stand on their own without reference to those documents. ## Commits - Commits must, as much as possible, do one "thing" and do it completely. It's fine for commits to work in multiple places across the codebase, if this is necessary to perform one coherent step of development. @@ -22,3 +22,4 @@ Co-Authored-By: Claude Opus 5.5 - You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Prompt your human to keep the entire description up to date as the issue or PR evolves. Remember, you are not allowed to edit an issue or PR description except for the "AI disclosure" section. - Unless your user tells you otherwise, you are also allowed to push to branches in forks, including branches that have associated PRs in ESCOMP/CTSM. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. + From 5a6d5a3730ecc97caa2fa4da094bd9470cf28482 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 11:22:23 -0600 Subject: [PATCH 21/59] AGENTS.md: No exceptions to editing issues/PRs. --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 749e33ca88..cd61b7bcf1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,9 +17,9 @@ Co-Authored-By: Claude Opus 5.5 ## GitHub issues and pull requests "The CTSM repo" in this section specifically refers to the GitHub repo ESCOMP/CTSM, not forks. -- **You may never submit, edit, or comment on an issue or PR in the CTSM repo, with one exception.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. The only exception is that you may edit the "AI disclosure" section to keep it accurate as the issue or PR evolves. +- **You may never submit, edit, or comment on an issue or PR in the CTSM repo** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. We consider it only fair that the contributing human do the same. - You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. Then follow the repository templates: `.github/PULL_REQUEST_TEMPLATE.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. -- You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Prompt your human to keep the entire description up to date as the issue or PR evolves. Remember, you are not allowed to edit an issue or PR description except for the "AI disclosure" section. +- You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Whenever you or your human pushes changes to a PR branch, review the existing PR description and prompt your human to update it if and where necessary. Remember, you are not allowed to edit an issue or PR description. - Unless your user tells you otherwise, you are also allowed to push to branches in forks, including branches that have associated PRs in ESCOMP/CTSM. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. From dd3c06571b6dba34c2526b713e7f937203fa8b6d Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 11:50:30 -0600 Subject: [PATCH 22/59] Add clm-coding-conventions.md. --- .../dev_guide/clm-coding-conventions.md | 469 ++++++++++++++++++ 1 file changed, 469 insertions(+) create mode 100644 doc/source/dev_guide/clm-coding-conventions.md diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md new file mode 100644 index 0000000000..04f8b46689 --- /dev/null +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -0,0 +1,469 @@ +(clm-coding-conventions-page)= + +# CLM coding conventions + +(clm-coding-conventions)= + +## CLM Coding Conventions + +This page is intended as a guide for CLM coding standards, practices and conventions. On this page, we focus on five items that we want all developers to concentrate on. Keep these in the back of your mind as you are programming and refer to them if you have a question. We are more than willing to work with you throughout the process (contact us at [CLM-CMT@cgd.ucar.edu](mailto:CLM-CMT@cgd.ucar.edu)). If code doesn't generally conform to these items then it will delay the tagging process and we will ask you to modify your code accordingly. + +Our past experiences have led us to document a more [Comprehensive list of standards](#comprehensive-list-of-standards) that we are striving for. You will find constructs that do not follow these guidelines and we are updating the legacy CLM code base as time and resources permit. + +### Comments + +1. Comment often and include explanations for algorithms and processes. Your code should be easily readable and understandable by anyone else who reads your work. + +#### Logical Branches + +include a comment after an **else** or **endif** statement. Use something that makes sense for the type of logical branch you are using. This is particularly important when there are large numbers of nested blocks. Look at the second if statement below for an even nicer way to accomplish the same thing without comments. + +```{code-block} text +:caption: Comments and Logical Branches + +if ( someLogical ) then ! someLogical controls the assignment of x or y + x = 0.0_r8 +else ! else someLogical + y = 0.0_r8 +endif ! if someLogical + +! Alternative to comments +fates_if: if (use_fates) then + lch4_if: if (use_lch4) then +[...] + end if lch4_if +end if fates_if +``` + +#### Pointer Intent + +If you pass information to a subroutine via a pointer in an associate block, include a comment as to the **intent** (OUT, IN, INOUT) of that pointer. This is in addition to a description of that pointer as well as the type and array dimensions. Also see [**Argument Passing**](#clm-conventions-argument-passing) on this page. + +```{code-block} text +:caption: Comments and Pointer Intent + +associate(& + ptrIn => derivedType%readOnlyInRoutine , & ! [character(len=8) (:)] intent = in used for x + ptrInOut => derivedType%readAndWriteInRoutine , & ! [real(r8) (:,:,:)] intent = inout used for y + ptrOut => derivedType%writeOnlyInRoutine & ! [real(r8) (:)] intent = out used for z +) +... +end associate +``` + +1. The meaning (semantic) of **intent** (out, in, inout) + 1. out - a variable is only set within a subroutine + 2. in - a variable is only passed into and used by a subroutine + 3. inout - a variable may be both modified and used within a subroutine + +(clm-conventions-argument-passing)= + +### Argument Passing + +1. The **intent** attribute of subroutine input/output variables is used. Argument lists should ***always*** use the **intent** attribute (try to have data be either IN or OUT and avoid INOUT if possible/reasonable). +2. There are currently three ways in the current code with which you can pass information to subroutines. By interface (best choice), by pointer (second best choice) and by using a global data type (a bad option, but sometimes still necessary within the current CLM framework). We are in the process of refactoring the code so that all data will be passed through the subroutine interface. New code coming in should not pass via global data unless all other options do not work. + +#### Subroutine Interface + +Use the intent keyword and keyword pairs if you have more than a few arguments. Try to consistently pass either all derived types or all FORTRAN types. Passing derived types can shorten the list of arguments and make it more understandable. Below are two examples from CLM, ([subsection i](#clm-conventions-clm-example), below) and RTM, ([subsection ii](#clm-conventions-rtm-example), below), respectively. + +(clm-conventions-clm-example)= + +##### CLM example from BandDiagonal::BandDiagonalMod.F90 + +###### Subroutine definition + +```{code-block} text +:caption: Interfaces::CLM. Example from BandDiagonal, definition + +subroutine BandDiagonal(bounds, lbj, ubj, jtop, jbot, numf, filter, nband, b, r, u) + ! + ! !DESCRIPTION: + ! Tridiagonal matrix solution + ! + ! !ARGUMENTS: + implicit none + type(bounds_type), intent(in) :: bounds ! bounds + integer , intent(in) :: lbj, ubj ! lbinning and ubing level indices + integer , intent(in) :: jtop( bounds%begc: ) ! top level for each column [col] + integer , intent(in) :: jbot( bounds%begc: ) ! bottom level for each column [col] + integer , intent(in) :: numf ! filter dimension + integer , intent(in) :: nband ! band width + integer , intent(in) :: filter(:) ! filter + real(r8), intent(in) :: b( bounds%begc: , 1: , lbj: ) ! compact band matrix [col, nband, j] + real(r8), intent(in) :: r( bounds%begc: , lbj: ) ! "r" rhs of linear system [col, j] + real(r8), intent(inout) :: u( bounds%begc: , lbj: ) ! solution [col, j] + ! + ! ! LOCAL VARIABLES: + integer :: j,ci,fc,info,m,n !indices + integer :: kl,ku !number of sub/super diagonals + integer, allocatable :: ipiv(:) !temporary + real(r8),allocatable :: ab(:,:),temp(:,:) !compact storage array + real(r8),allocatable :: result(:) + + !----------------------------------------------------------------------- + + ! Enforce expected array sizes + SHR_ASSERT_ALL((ubound(jtop) == (/bounds%endc/)), errMsg(__FILE__, __LINE__)) + SHR_ASSERT_ALL((ubound(jbot) == (/bounds%endc/)), errMsg(__FILE__, __LINE__)) + SHR_ASSERT_ALL((ubound(b) == (/bounds%endc, nband, ubj/)), errMsg(__FILE__, __LINE__)) + SHR_ASSERT_ALL((ubound(r) == (/bounds%endc, ubj/)), errMsg(__FILE__, __LINE__)) + SHR_ASSERT_ALL((ubound(u) == (/bounds%endc, ubj/)), errMsg(__FILE__, __LINE__)) +``` + +The definition above illustrates a few important points. +- Specify the lower bounds of array arguments (this is needed for the subroutine to operate properly in a threaded region) +- Do **not** specify the upper bounds of array arguments (doing so can prevent the compiler from checking for array size agreement between the caller and callee, and can carry a performance penalty) +- The first set of code in the routine should be assertions for the expected array upper bounds + +The above code demonstrates a few stylistic points as well: +- Specify the lower bound explicitly, even when it is 1 (see the 'b' argument, above) +- Put a space after each ':' for readability +- Add comments about expected array sizes, as in \[col, nband, j\] + +###### Subroutine call + +Follow this example in which BandDiagonal is called from SoilTemperatureMod.F90: + +```{code-block} text +:caption: Interfaces::CLM. Example from BandDiagonal, call + +call BandDiagonal(bounds, -nlevsno, nlevgrnd, jtop(begc:endc), jbot(begc:endc), & + num_nolakec, filter_nolakec, nband, bmatrix(begc:endc, :, :), & + rvector(begc:endc, :), tvector(begc:endc, :)) +``` + +- The important point here is that the lower and upper bounds are explicitly specified for the gridcell / landunit / col / pft dimension of all array arguments. This is important for threading to work properly. +- Even for local variables whose dimensions only go begc:endc, please explicitly specify the dimensions as above when passing the array to a subroutine. This will ensure that threading continues to work if the variable's dimensions change (e.g., if it is pulled into clmtype, and thus has dimensions that span the proc_bounds rather than the clump_bounds). + +(clm-conventions-rtm-example)= + +##### RTM example from RtmMod.F90 + +```{code-block} text +:caption: Interfaces::RTM. Example from RtmMod.F90 + +! +! The call of the routine +! +call RtmFloodInit (frivinp_rtm, begr, endr, nt_rtm, & + runoff%fthresh( begr:endr ), & + evel( begr:endr , : ), & + runoff%gindex( begr:endr ), & + runoff%lnumr, & + flood_active, & + effvel_active) +... +! +! The interface definition +! +subroutine RtmFloodInit(frivinp, begr, endr, nt_rtm, fthresh, evel, & + gindex , & + lnumr , & + is_rtmflood_on, & + is_effvel_on ) +... + ! Subroutine arguments + ! in mode arguments + character(len=*), intent(in) :: frivinp + integer , intent(in) :: begr, endr, nt_rtm + logical , intent(in) :: is_rtmflood_on !control flooding + logical , intent(in) :: is_effvel_on !control eff. velocity + integer , intent(in) :: gindex( begr: ) ! global index [begr:endr] + integer , intent(in) :: lnumr ! local number of cells +... +! check bounds of arrays + SHR_ASSERT_ALL((ubound(fthresh) == (/endr/)), errMsg(__FILE__, __LINE__)) + SHR_ASSERT_ALL((ubound(gindex) == (/endr/)), errMsg(__FILE__, __LINE__)) + SHR_ASSERT_ALL((ubound(evel) == (/endr, nt_rtm/)), errMsg(__FILE__, __LINE__)) +... +``` + +#### Pointer + +We are moving away from using pointers as a way pass information into routines. We still allow this but with the use of an associate statement. + +```{code-block} text +:caption: Comments and Pointer Intent + +associate(& + ptrIn => derivedType%readOnlyInRoutine , & ! [character(len=8) (:)] intent = in used for x + ptrInOut => derivedType%readAndWriteInRoutine , & ! [real(r8) (:,:,:)] intent = inout used for y + ptrOut => derivedType%writeOnlyInRoutine & ! [real(r8) (:)] intent = out used for z +) +... +end associate +``` + +#### Global data + +We are moving away from using global data as a way pass information into routines. Unless you are extending existing functionality (e.g. using a namelist variable to control some execution) we will generally not allow any new use of a global variable. The other exception to this rule is that it is OK to you use global type declarations. + +```{code-block} text +:caption: Global Data. Global data in CanopyFluxesMod.F90 + +use clm_varctl , only: iulog, use_cn, use_lch4, use_c13, use_c14, use_cndv +! + if ( use_c13 ) then + c13o2(p) = forc_pc13o2(g) + endif ! use_c13 +! +``` + +```{code-block} text +:caption: Global Data. Using a global type declaration + +use decompMod , only : bounds_type ! using a global type declaration +... +subroutine CNSoilLittVertTransp(bounds, num_soilc, filter_soilc) +... +type(bounds_type), intent(in) :: bounds ! bounds +... +``` + +### Indentation + +1. Indent consistently and make sure your auto-tab function in your editor converts tabs to spaces. + 1. Indent of most blocks (do, if, while, etc.): 3 spaces + 2. Indent of "program" blocks (program, module, subroutine, function): 2 spaces + 3. Indent of "associate" blocks: 0 spaces + 4. Indent of continuation lines: 5 (this can vary based on look and feel) + + ```{code-block} text + :caption: Indentation + + ! a dash, '-', represents a space + --use thisModule , only : thisRoutine + ! + --subroutine foo + ----use thatModule , only : thatRoutine + ----associate ( & + -------ptr1 => someDerivedType%ptr1 , & + -------ptr2 => someDerivedType%ptr2 & + ----) + ----if ( someLogical ) then + -------x=x+1 + ! leave a line before and after statements that stand alone. + -------if (x == 0) then endrun() + ! leave a line before and after statements that stand alone. + -------do while ( x <= 1000 ) + ----------! do some stuff + ----------z = 1.0_r8 / radius + -------end do ! end x<=1000 + ----endif ! someLogical + ! + ----end associate + --end subroutine + ``` +2. Do not leave hanging white space at the end of any line of code; git diff shows this in red spaces. +3. Do not tabularize code by adding extra spaces to any line of code. It may be tempting to do this for better readability, but it also takes time to manage code that needs realignment when new code comes in. + +### Statements and Subroutines + +1. Don't repeat yourself. If you are copying and pasting code, then write a subroutine or function to encapsulate functionality. + + ```{code-block} text + :caption: Example of repeated code - Do + + ! + ! an example of using a subprogram to remove repeated code where + ! the max daylength is calculated in a function. + ! + ! From iniTimeConst: + + ! initialize maximum daylength, based on latitude and maximum declination + ! maximum declination hardwired for present-day orbital parameters, + ! ± 23.4667 degrees = ± 0.409571 radians, use negative value for S. Hem + max_decl = 0.409571 + if (grc%lat(g) .lt. 0._r8) max_decl = -max_decl + max_dayl(c) = calcMaxDayFunc( grc%lat(g) , max_decl ) + + ! From CanopyFluxesMod: + + ! calculate daylength + dayl(c) = calcMaxDayFunc( lat(g) , decl(c) ) + + ! From CNPhenologyMod (copied & pasted in two places in this module): + + lat = (SHR_CONST_PI/180._r8)*grc%latdeg(pgridcell(p)) + dayl(p) = calcMaxDayFunc( lat , decl(c) ) + ``` + + ```{code-block} text + :caption: Example of repeated code - Don't do + + ! + ! an example of what not to do in terms of repeating code. + ! The max daylength calculation is repeated. + ! + ! From iniTimeConst: + + ! initialize maximum daylength, based on latitude and maximum declination + ! maximum declination hardwired for present-day orbital parameters, + ! ± 23.4667 degrees = ± 0.409571 radians, use negative value for S. Hem + max_decl = 0.409571 + if (grc%lat(g) .lt. 0._r8) max_decl = -max_decl + temp = -(sin(grc%lat(g))*sin(max_decl))/(cos(grc%lat(g)) * cos(max_decl)) + temp = min(1._r8,max(-1._r8,temp)) + max_dayl(c) = 2.0_r8 * 13750.9871_r8 * acos(temp) + + ! From CanopyFluxesMod: + + ! calculate daylength + temp = -(sin(lat(g))*sin(decl(c)))/(cos(lat(g)) * cos(decl(c))) + temp = min(1._r8,max(-1._r8,temp)) + dayl = 2.0_r8 * 13750.9871_r8 * acos(temp) + + ! From CNPhenologyMod (copied & pasted in two places in this module): + + lat = (SHR_CONST_PI/180._r8)*grc%latdeg(pgridcell(p)) + temp = -(sin(lat)*sin(decl(c)))/(cos(lat) * cos(decl(c))) + temp = min(1._r8,max(-1._r8,temp)) + dayl(p) = 2.0_r8 * 13750.9871_r8 * acos(temp) + ``` +2. Fortran allows you to place multiple statements on one line. Don't do this. + + ```{code-block} text + :caption: Multiple Statements - Do + + ! do this: + x = 0 + y = 0 + z = 0 + ``` + + ```{code-block} text + :caption: Multiple Statements - Don't do + + ! not this: + x = 0 ; y=0; z=0 + ``` +3. Use temporary variables often + + ```{code-block} text + :caption: Temporary Variables - Do + + ! do this: + someFactor = ( const1/const2 ) * const3 + additiveFluxes = ( add1Flx + add2Flx + add3Flx ) ** someFactor + subFluxes = (sub1Flx + sub2Flx + sub3Flx) ** someFactor + sumVal = additiveFluxes + subFluxes + ``` + + ```{code-block} text + :caption: Temporary Variables - Don't do + + ! not this: + sumVal = (( add1Flx + add2Flx + add3Flx ) ** (( const1/const2 ) * const3 )) + ((sub1Flx + sub2Flx + sub3Flx) ** (( const1/const2 ) * const3 )) + ``` +4. Keep subroutines short and organize the code into the smallest reasonable chunk of code that can stand on its own. Basically, you're looking for dividing routines into logical units of work. For example, don't put initialization, some science and then diagnostics all in one routine, these would be best divided into 4 routines; in this case one routine that calls three additional routines. + - Use parenthesis to clarify you statements even when the Fortran precedence rules will evaluate items in the correct order. + +### Preprocessor Macros (CPP Tokens) + +- We are in the process of removing CPP Tokens from all of CLM (see our refactoring page ) and will not accept code using them. + + ```{code-block} text + :caption: Preprocessor Macros (CPP Tokens) - Do + + ! do this: + if (useNewPhysics == .true.) then + ... + ! do some new physics + ... + endif + ``` + + ```{code-block} text + :caption: Preprocessor Macros (CPP Tokens) - Don't do + + ! not this: + #if (defined USENEWPHYSICS) + ... + ! do some new physics + ... + #endif + ``` + +(comprehensive-list-of-standards)= + +## Comprehensive list of standards + +These conventions cover some of the more detailed aspects of CLM code design. It is intended to compliment and extend the information found on the [previous page](#clm-coding-conventions). If you have questions please contact us at [CLM-CMT@cgd.ucar.edu](mailto:CLM-CMT@cgd.ucar.edu). + +### General Guidelines + +1. We support Fortran 2003 language features with a few exceptions. Information regarding compiler support for Fortran 2003 features may be found at the [fortran wiki](http://fortranwiki.org/fortran/show/Fortran+2003+status) . The three Fortran 2003 feature that we can't support due to lack of compiler implementation are: + 1. finalization + 2. parameterized derived types + 3. derived type I/O +2. Use **implicit none**. All variables must be explicitly typed. +3. **Don't repeat yourself**. Duplicated code is difficult to maintain. If you find yourself using copy and paste more than once, create a new function or subroutine that encapsulates the desired functionality. +4. Try to implement subroutine and function interface with argument lists of 9 or less. If you have lists longer than this, break up the functionality into multiple methods and/or use derived types for higher level interfaces. Try to have argument lists short enough that you can make unit-tests for them. +5. If you have argument lists greater than 8 -- you must call such routines using the keyword-pair form for all arguments (but see 3 above). + +### Performance, debugging and optimization + +1. Don't mix up C/C++ and Fortran memory access order; it will slow your code down drastically. If you have question contact a CLM-CMT. +2. Debug with a debugger (totalview, gdb, idb, pgdbg, etc...) it will save you a lot of time finding errors. For an example see this CISL [example](http://www2.cisl.ucar.edu/resources/yellowstone/code_dev/debugging) + 1. Adding Write statements to your code and dumping variable values also can work very well in finding problems. +3. Be aware of the memory footprint of additional code. Try to keep increases in memory use low. Use [Valgrind](http://valgrind.org/) or similar tools often during your development process to track and monitor memory increases, changes, leaks, etc.... +4. Performance + 1. Regarding vectorization. If you feel your code performance is suffering there are some ideas [here](http://software.intel.com/en-us/intel-vectorization-tools) under the Fortran section. + 2. How you access derived type members can change performance. See for example some ideas regarding [derived types](http://software.intel.com/sites/products/documentation/doclib/stdxe/2013/composerxe/compiler/fortran-lin/index.htm#GUID-AFE9908C-BDC7-47DE-BEE6-2C7FBA382F4B.htm) and a discussion on [alignment](http://software.intel.com/sites/products/documentation/doclib/stdxe/2013/composerxe/compiler/fortran-mac/GUID-E9F21218-F280-4521-86B2-FAE99FF0BA0F.htm) + +### Modularity + +1. Data types, data and methods should be encapsulated within a module if they are used in that module. If data types, data and/or methods are used outside of the module they are declared in, they must be made publicly available. +2. Data should also be accessible at the most private level possible. In other words: + 1. If a variable is only used in one subroutine it should be local to that subroutine + 2. If a variable is only local to one module then it is declared private to that module. + 3. Public data for modules should be used sparingly. +3. Only data required for output to history files should be in clmtype.F90. +4. A separate restart module/subroutine called from CLM restFileMod.F90 should be used to facilitate reading/writing of information to restart files. +5. In general data initialized in clmtype should have a separate module/subroutine to do so. +6. The number of variables added to clmtype needs to be limited. + +### Guidelines for Fortran statements + +1. Fortran2003 deprecated features will not be accepted in new code (equivalence, common blocks, block data, etc.). +2. Use statements – should nearly always use the **only** construct to define what variables are being used from a given module. The only case when this is not to be done, is when the list of variables is so long to make this unmanageable taking up more than 6 continue lines (for example with use of the clmtype module). +3. The "intent" attribute of subroutine input/output variables is used. Argument lists should ALWAYS use the INTENT attribute (try to have data be either IN or OUT and avoid INOUT if possible/reasonable). +4. Try to limit the use of the "use statement" to other modules to subroutines/functions and read-only parameters. +5. Data that is read-only, or output from a subroutine/function should be passed down using argument lists. +6. Modules explicitly declare public subroutines/functions at the module level. +7. By default all modules should have variables/methods/types declared to be private. +8. Print statements are not allowed, use write instead. +9. Stop statements will not be accepted in new code – use the endrun subroutine part of the CLM abortutils module. +10. Debugging statements should be removed prior to check in. If there is a need to leave them in, then they will be controlled by a logical or integer control variable. +11. Don't hard-code "magic numbers". For example, hard-coding a variable to "5" in order to make sure a certain path of an if branch is taken. Use the parameter statement at the top of the subroutine to set such variables. +12. Use symbolic logical operators (\<, \>, == etc.) rather than word (.lt., .gt. .eq.). + +### Guidelines for working within the CLM codebase + +1. We no longer accept new code with preprocessor macros (CPP tokens). +2. Namelist items should be defined in the XML files relevant to clm4_5 and clm4_0: + 1. models/lnd/clm/bld/namelist_files/namelist_definition_clm4_5.xml + 2. models/lnd/clm/bld/namelist_files/namelist_definition_clm4_0.xml +3. Type declarations make use of the shr_kinds_mod module. +4. All write statements are to iulog from clm_varctl.F90 or to another appropriate logical unit. +5. Write statements should be within "if ( masterproc )" if statement unless output by all tasks is really desired (such as for error statements). +6. Unit numbers are to be controlled using the CLM module fileutils.F90. +7. The module spmdMod should be used to get MPI information such as masterproc, iam etc. +8. The ncdio_pio module should be used to read/write/define NetCDF input/output data. +9. Modules clmvarcon or shr_const_mod should be used to define parameters in common with CLM and/or CESM. +10. Module clm_time_manager should be used to get time/date information. In particular length of day, month, or year information should be queried from clm_time_manager. +11. CLM parameters should be retrieved from the clm_varcon, clm_varpar and clm_varctl modules. +12. If writing is done in an initialization subroutine iulog should be flushed using shr_sys_flush at the end of the subroutine. +13. Evaluate new history fields being added. If they are not critical leave out of the code base; if they are only needed rarely, make them "inactive" by default. + +### Guidelines for adding new datasets + +1. Input datasets or raw datasets used to create input datasets (such as those that require the mksurfdata tool) need to be imported into the Subversion inputdata repository by one of the CLM-CMTs. CLM-CMTs have the necessary permissions to do this and can also stage data on DIN_LOC_ROOT for NCAR internal machines. +2. Input datasets should have names that describe what they are, contain their resolution, and a have creation date at the end (i.e. \_cYYMMDD). Data should be in NetCDF format ending in a .nc extension. +3. All input datasets will be entered into the CLM XML database in the models/lnd/clm/bld/namelist_files directory. +4. CF-metadata conventions should be followed for the files. +5. The attributes of "units" and "long_name" should be set for all variables. Variables with missing data should have set the "missing_value" and "\_FillValue" attributes. +6. The attributes "Conventions", "source" and/or "history" should be set as global attributes on the file (references, institution, title and date should be considered as well). +7. Filenames should not be hardcoded into CLM code, they should be entered in by a namelist. +8. File sizes or number of time samples or records, should not be hardcoded into CLM code, but read in from the file. From d9a138e1bf29fb4b17b6c9279b62b2af10088cfe Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 11:52:26 -0600 Subject: [PATCH 23/59] clm-coding-conventions.md: No numbers > H3. --- .../dev_guide/clm-coding-conventions.md | 36 ++++++++++++++----- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index 04f8b46689..06a640b93b 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -14,7 +14,9 @@ Our past experiences have led us to document a more [Comprehensive list of stand 1. Comment often and include explanations for algorithms and processes. Your code should be easily readable and understandable by anyone else who reads your work. -#### Logical Branches +```{rubric} Logical Branches +:heading-level: 4 +``` include a comment after an **else** or **endif** statement. Use something that makes sense for the type of logical branch you are using. This is particularly important when there are large numbers of nested blocks. Look at the second if statement below for an even nicer way to accomplish the same thing without comments. @@ -35,7 +37,9 @@ fates_if: if (use_fates) then end if fates_if ``` -#### Pointer Intent +```{rubric} Pointer Intent +:heading-level: 4 +``` If you pass information to a subroutine via a pointer in an associate block, include a comment as to the **intent** (OUT, IN, INOUT) of that pointer. This is in addition to a description of that pointer as well as the type and array dimensions. Also see [**Argument Passing**](#clm-conventions-argument-passing) on this page. @@ -63,15 +67,21 @@ end associate 1. The **intent** attribute of subroutine input/output variables is used. Argument lists should ***always*** use the **intent** attribute (try to have data be either IN or OUT and avoid INOUT if possible/reasonable). 2. There are currently three ways in the current code with which you can pass information to subroutines. By interface (best choice), by pointer (second best choice) and by using a global data type (a bad option, but sometimes still necessary within the current CLM framework). We are in the process of refactoring the code so that all data will be passed through the subroutine interface. New code coming in should not pass via global data unless all other options do not work. -#### Subroutine Interface +```{rubric} Subroutine Interface +:heading-level: 4 +``` Use the intent keyword and keyword pairs if you have more than a few arguments. Try to consistently pass either all derived types or all FORTRAN types. Passing derived types can shorten the list of arguments and make it more understandable. Below are two examples from CLM, ([subsection i](#clm-conventions-clm-example), below) and RTM, ([subsection ii](#clm-conventions-rtm-example), below), respectively. (clm-conventions-clm-example)= -##### CLM example from BandDiagonal::BandDiagonalMod.F90 +```{rubric} CLM example from BandDiagonal::BandDiagonalMod.F90 +:heading-level: 5 +``` -###### Subroutine definition +```{rubric} Subroutine definition +:heading-level: 6 +``` ```{code-block} text :caption: Interfaces::CLM. Example from BandDiagonal, definition @@ -121,7 +131,9 @@ The above code demonstrates a few stylistic points as well: - Put a space after each ':' for readability - Add comments about expected array sizes, as in \[col, nband, j\] -###### Subroutine call +```{rubric} Subroutine call +:heading-level: 6 +``` Follow this example in which BandDiagonal is called from SoilTemperatureMod.F90: @@ -138,7 +150,9 @@ call BandDiagonal(bounds, -nlevsno, nlevgrnd, jtop(begc:endc), jbot(begc:endc), (clm-conventions-rtm-example)= -##### RTM example from RtmMod.F90 +```{rubric} RTM example from RtmMod.F90 +:heading-level: 5 +``` ```{code-block} text :caption: Interfaces::RTM. Example from RtmMod.F90 @@ -179,7 +193,9 @@ subroutine RtmFloodInit(frivinp, begr, endr, nt_rtm, fthresh, evel, & ... ``` -#### Pointer +```{rubric} Pointer +:heading-level: 4 +``` We are moving away from using pointers as a way pass information into routines. We still allow this but with the use of an associate statement. @@ -195,7 +211,9 @@ associate(& end associate ``` -#### Global data +```{rubric} Global data +:heading-level: 4 +``` We are moving away from using global data as a way pass information into routines. Unless you are extending existing functionality (e.g. using a namelist variable to control some execution) we will generally not allow any new use of a global variable. The other exception to this rule is that it is OK to you use global type declarations. From 2c417c862a170531b6dfb6194df38fbf14d4ed8c Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 11:55:03 -0600 Subject: [PATCH 24/59] clm-coding-conventions.md: Remove outdated emails --- doc/source/dev_guide/clm-coding-conventions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index 06a640b93b..b813c0d6cc 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -6,7 +6,7 @@ ## CLM Coding Conventions -This page is intended as a guide for CLM coding standards, practices and conventions. On this page, we focus on five items that we want all developers to concentrate on. Keep these in the back of your mind as you are programming and refer to them if you have a question. We are more than willing to work with you throughout the process (contact us at [CLM-CMT@cgd.ucar.edu](mailto:CLM-CMT@cgd.ucar.edu)). If code doesn't generally conform to these items then it will delay the tagging process and we will ask you to modify your code accordingly. +This page is intended as a guide for CLM coding standards, practices and conventions. On this page, we focus on five items that we want all developers to concentrate on. Keep these in the back of your mind as you are programming and refer to them if you have a question. We are more than willing to work with you throughout the process as needed; please contact us at [ctsm-support@ucar.edu](mailto:ctsm-support@ucar.edu) or on your GitHub discussion, issue, or pull request. If code doesn't generally conform to these items then it will delay the tagging process and we will ask you to modify your code accordingly. Our past experiences have led us to document a more [Comprehensive list of standards](#comprehensive-list-of-standards) that we are striving for. You will find constructs that do not follow these guidelines and we are updating the legacy CLM code base as time and resources permit. @@ -407,7 +407,7 @@ type(bounds_type), intent(in) :: bounds ! bounds ## Comprehensive list of standards -These conventions cover some of the more detailed aspects of CLM code design. It is intended to compliment and extend the information found on the [previous page](#clm-coding-conventions). If you have questions please contact us at [CLM-CMT@cgd.ucar.edu](mailto:CLM-CMT@cgd.ucar.edu). +These conventions cover some of the more detailed aspects of CLM code design. It is intended to compliment and extend the information found on the [previous page](#clm-coding-conventions). If you have questions please contact us at [ctsm-support@ucar.edu](mailto:ctsm-support@ucar.edu) or on your GitHub discussion, issue, or pull request. ### General Guidelines From e8e0bfa6345aef3c07ad2066e7cfbe3778cfb28b Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 12:07:51 -0600 Subject: [PATCH 25/59] clm-coding-conventions.md: Now orphan --- doc/source/dev_guide/clm-coding-conventions.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index b813c0d6cc..5d76ff3f90 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -1,3 +1,7 @@ +--- +orphan: true +--- + (clm-coding-conventions-page)= # CLM coding conventions @@ -411,7 +415,7 @@ These conventions cover some of the more detailed aspects of CLM code design. It ### General Guidelines -1. We support Fortran 2003 language features with a few exceptions. Information regarding compiler support for Fortran 2003 features may be found at the [fortran wiki](http://fortranwiki.org/fortran/show/Fortran+2003+status) . The three Fortran 2003 feature that we can't support due to lack of compiler implementation are: +1. We support Fortran 2003 language features with a few exceptions. Information regarding compiler support for Fortran 2003 features may be found at the [fortran wiki](http://fortranwiki.org/fortran/show/Fortran+2003+status). The three Fortran 2003 feature that we can't support due to lack of compiler implementation are: 1. finalization 2. parameterized derived types 3. derived type I/O From 4d69270376d82d738ea680a8527cb47ed7551346 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 12:13:53 -0600 Subject: [PATCH 26/59] clm-coding-conventions.md: Update Fortran feature support list. --- doc/source/dev_guide/clm-coding-conventions.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index 5d76ff3f90..d57368516c 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -415,10 +415,7 @@ These conventions cover some of the more detailed aspects of CLM code design. It ### General Guidelines -1. We support Fortran 2003 language features with a few exceptions. Information regarding compiler support for Fortran 2003 features may be found at the [fortran wiki](http://fortranwiki.org/fortran/show/Fortran+2003+status). The three Fortran 2003 feature that we can't support due to lack of compiler implementation are: - 1. finalization - 2. parameterized derived types - 3. derived type I/O +1. We support [Fortran 2003](http://fortranwiki.org/fortran/show/Fortran+2003+status) language features with a few exceptions, along with some [Fortran 2008](http://fortranwiki.org/fortran/show/Fortran+2008+status) features. The Fortran 2003 features that we don't implement are parameterized derived types and derived type I/O. The Fortran 2008 features that we do implement are `newunit=` in `open`, the `erf` and `gamma` intrinsics, and `storage_size`. 2. Use **implicit none**. All variables must be explicitly typed. 3. **Don't repeat yourself**. Duplicated code is difficult to maintain. If you find yourself using copy and paste more than once, create a new function or subroutine that encapsulates the desired functionality. 4. Try to implement subroutine and function interface with argument lists of 9 or less. If you have lists longer than this, break up the functionality into multiple methods and/or use derived types for higher level interfaces. Try to have argument lists short enough that you can make unit-tests for them. From 3708e932c4f002275d4f4acada4147a922a853cf Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 12:15:16 -0600 Subject: [PATCH 27/59] clm-coding-conventions.md: Remove references to "CMTs". --- doc/source/dev_guide/clm-coding-conventions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index d57368516c..f545906e2f 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -423,7 +423,7 @@ These conventions cover some of the more detailed aspects of CLM code design. It ### Performance, debugging and optimization -1. Don't mix up C/C++ and Fortran memory access order; it will slow your code down drastically. If you have question contact a CLM-CMT. +1. Don't mix up C/C++ and Fortran memory access order; it will slow your code down drastically. 2. Debug with a debugger (totalview, gdb, idb, pgdbg, etc...) it will save you a lot of time finding errors. For an example see this CISL [example](http://www2.cisl.ucar.edu/resources/yellowstone/code_dev/debugging) 1. Adding Write statements to your code and dumping variable values also can work very well in finding problems. 3. Be aware of the memory footprint of additional code. Try to keep increases in memory use low. Use [Valgrind](http://valgrind.org/) or similar tools often during your development process to track and monitor memory increases, changes, leaks, etc.... @@ -478,7 +478,7 @@ These conventions cover some of the more detailed aspects of CLM code design. It ### Guidelines for adding new datasets -1. Input datasets or raw datasets used to create input datasets (such as those that require the mksurfdata tool) need to be imported into the Subversion inputdata repository by one of the CLM-CMTs. CLM-CMTs have the necessary permissions to do this and can also stage data on DIN_LOC_ROOT for NCAR internal machines. +1. Input datasets or raw datasets used to create input datasets (such as those that require the mksurfdata tool) need to be imported into by one of the CLM maintainers, who have the necessary permissions to do this and can also stage data on DIN_LOC_ROOT for NCAR internal machines. 2. Input datasets should have names that describe what they are, contain their resolution, and a have creation date at the end (i.e. \_cYYMMDD). Data should be in NetCDF format ending in a .nc extension. 3. All input datasets will be entered into the CLM XML database in the models/lnd/clm/bld/namelist_files directory. 4. CF-metadata conventions should be followed for the files. From 302b329f2fcd3ea47ca164de49aac1cead937799 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 12:15:42 -0600 Subject: [PATCH 28/59] clm-coding-conventions.md: Remove reference to Yellowstone. --- doc/source/dev_guide/clm-coding-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index f545906e2f..6b9269be87 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -424,7 +424,7 @@ These conventions cover some of the more detailed aspects of CLM code design. It ### Performance, debugging and optimization 1. Don't mix up C/C++ and Fortran memory access order; it will slow your code down drastically. -2. Debug with a debugger (totalview, gdb, idb, pgdbg, etc...) it will save you a lot of time finding errors. For an example see this CISL [example](http://www2.cisl.ucar.edu/resources/yellowstone/code_dev/debugging) +2. Debug with a debugger (totalview, gdb, idb, pgdbg, etc...) it will save you a lot of time finding errors. 1. Adding Write statements to your code and dumping variable values also can work very well in finding problems. 3. Be aware of the memory footprint of additional code. Try to keep increases in memory use low. Use [Valgrind](http://valgrind.org/) or similar tools often during your development process to track and monitor memory increases, changes, leaks, etc.... 4. Performance From 07088001d1cf9aa1adebef5f62277cedff22701d Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 12:20:32 -0600 Subject: [PATCH 29/59] clm-coding-conventions.md: Update refs to XML files --- doc/source/dev_guide/clm-coding-conventions.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index 6b9269be87..bce2f05780 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -461,9 +461,7 @@ These conventions cover some of the more detailed aspects of CLM code design. It ### Guidelines for working within the CLM codebase 1. We no longer accept new code with preprocessor macros (CPP tokens). -2. Namelist items should be defined in the XML files relevant to clm4_5 and clm4_0: - 1. models/lnd/clm/bld/namelist_files/namelist_definition_clm4_5.xml - 2. models/lnd/clm/bld/namelist_files/namelist_definition_clm4_0.xml +2. Namelist items should be defined in the XML files in `bld/namelist_files/`. 3. Type declarations make use of the shr_kinds_mod module. 4. All write statements are to iulog from clm_varctl.F90 or to another appropriate logical unit. 5. Write statements should be within "if ( masterproc )" if statement unless output by all tasks is really desired (such as for error statements). @@ -480,7 +478,7 @@ These conventions cover some of the more detailed aspects of CLM code design. It 1. Input datasets or raw datasets used to create input datasets (such as those that require the mksurfdata tool) need to be imported into by one of the CLM maintainers, who have the necessary permissions to do this and can also stage data on DIN_LOC_ROOT for NCAR internal machines. 2. Input datasets should have names that describe what they are, contain their resolution, and a have creation date at the end (i.e. \_cYYMMDD). Data should be in NetCDF format ending in a .nc extension. -3. All input datasets will be entered into the CLM XML database in the models/lnd/clm/bld/namelist_files directory. +3. All input datasets will be entered into the CLM XML database in the `bld/namelist_files/` directory. 4. CF-metadata conventions should be followed for the files. 5. The attributes of "units" and "long_name" should be set for all variables. Variables with missing data should have set the "missing_value" and "\_FillValue" attributes. 6. The attributes "Conventions", "source" and/or "history" should be set as global attributes on the file (references, institution, title and date should be considered as well). From 17a9905e022bb10f2b0e3cb25c20ef69a83696e9 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 12:27:23 -0600 Subject: [PATCH 30/59] clm-coding-conventions.md: Make most code blocks fortran. --- .../dev_guide/clm-coding-conventions.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index bce2f05780..3cea60ebd6 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -24,7 +24,7 @@ Our past experiences have led us to document a more [Comprehensive list of stand include a comment after an **else** or **endif** statement. Use something that makes sense for the type of logical branch you are using. This is particularly important when there are large numbers of nested blocks. Look at the second if statement below for an even nicer way to accomplish the same thing without comments. -```{code-block} text +```{code-block} fortran :caption: Comments and Logical Branches if ( someLogical ) then ! someLogical controls the assignment of x or y @@ -47,7 +47,7 @@ end if fates_if If you pass information to a subroutine via a pointer in an associate block, include a comment as to the **intent** (OUT, IN, INOUT) of that pointer. This is in addition to a description of that pointer as well as the type and array dimensions. Also see [**Argument Passing**](#clm-conventions-argument-passing) on this page. -```{code-block} text +```{code-block} fortran :caption: Comments and Pointer Intent associate(& @@ -141,7 +141,7 @@ The above code demonstrates a few stylistic points as well: Follow this example in which BandDiagonal is called from SoilTemperatureMod.F90: -```{code-block} text +```{code-block} fortran :caption: Interfaces::CLM. Example from BandDiagonal, call call BandDiagonal(bounds, -nlevsno, nlevgrnd, jtop(begc:endc), jbot(begc:endc), & @@ -203,7 +203,7 @@ subroutine RtmFloodInit(frivinp, begr, endr, nt_rtm, fthresh, evel, & We are moving away from using pointers as a way pass information into routines. We still allow this but with the use of an associate statement. -```{code-block} text +```{code-block} fortran :caption: Comments and Pointer Intent associate(& @@ -221,7 +221,7 @@ end associate We are moving away from using global data as a way pass information into routines. Unless you are extending existing functionality (e.g. using a namelist variable to control some execution) we will generally not allow any new use of a global variable. The other exception to this rule is that it is OK to you use global type declarations. -```{code-block} text +```{code-block} fortran :caption: Global Data. Global data in CanopyFluxesMod.F90 use clm_varctl , only: iulog, use_cn, use_lch4, use_c13, use_c14, use_cndv @@ -232,7 +232,7 @@ use clm_varctl , only: iulog, use_cn, use_lch4, use_c13, use_c14, use_cndv ! ``` -```{code-block} text +```{code-block} fortran :caption: Global Data. Using a global type declaration use decompMod , only : bounds_type ! using a global type declaration @@ -251,7 +251,7 @@ type(bounds_type), intent(in) :: bounds ! bounds 3. Indent of "associate" blocks: 0 spaces 4. Indent of continuation lines: 5 (this can vary based on look and feel) - ```{code-block} text + ```{code-block} fortran :caption: Indentation ! a dash, '-', represents a space @@ -284,7 +284,7 @@ type(bounds_type), intent(in) :: bounds ! bounds 1. Don't repeat yourself. If you are copying and pasting code, then write a subroutine or function to encapsulate functionality. - ```{code-block} text + ```{code-block} fortran :caption: Example of repeated code - Do ! @@ -311,7 +311,7 @@ type(bounds_type), intent(in) :: bounds ! bounds dayl(p) = calcMaxDayFunc( lat , decl(c) ) ``` - ```{code-block} text + ```{code-block} fortran :caption: Example of repeated code - Don't do ! @@ -345,7 +345,7 @@ type(bounds_type), intent(in) :: bounds ! bounds ``` 2. Fortran allows you to place multiple statements on one line. Don't do this. - ```{code-block} text + ```{code-block} fortran :caption: Multiple Statements - Do ! do this: @@ -354,7 +354,7 @@ type(bounds_type), intent(in) :: bounds ! bounds z = 0 ``` - ```{code-block} text + ```{code-block} fortran :caption: Multiple Statements - Don't do ! not this: @@ -362,7 +362,7 @@ type(bounds_type), intent(in) :: bounds ! bounds ``` 3. Use temporary variables often - ```{code-block} text + ```{code-block} fortran :caption: Temporary Variables - Do ! do this: @@ -372,7 +372,7 @@ type(bounds_type), intent(in) :: bounds ! bounds sumVal = additiveFluxes + subFluxes ``` - ```{code-block} text + ```{code-block} fortran :caption: Temporary Variables - Don't do ! not this: @@ -385,7 +385,7 @@ type(bounds_type), intent(in) :: bounds ! bounds - We are in the process of removing CPP Tokens from all of CLM (see our refactoring page ) and will not accept code using them. - ```{code-block} text + ```{code-block} fortran :caption: Preprocessor Macros (CPP Tokens) - Do ! do this: @@ -396,7 +396,7 @@ type(bounds_type), intent(in) :: bounds ! bounds endif ``` - ```{code-block} text + ```{code-block} fortran :caption: Preprocessor Macros (CPP Tokens) - Don't do ! not this: From 9ab2ab385e8c2deb98a3b04f280ec62ddb3b8055 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 12:31:12 -0600 Subject: [PATCH 31/59] Refer to new coding guidelines page. --- AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cd61b7bcf1..f97e6aba64 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -**Read and obey all standards described in `CONTRIBUTING.md`, including the webpage linked under "Coding Practices and Style."** +**Read and obey all standards described in `CONTRIBUTING.md`, including the webpage linked under "Coding Practices and Style," which you can also find in this repo at `doc/source/dev_guide/clm-coding-conventions.md`.** ## General rules - You must assume that any development design or implementation plan documents will not be brought into the repository upon merge. It's fine to commit them and even open pull requests with them present, but the maintainers will require that you remove them before merge. Therefore, all work you do -- code comments, persistent documentation, commit messages -- must stand on their own without reference to those documents. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c970f325e6..c552d9ee5b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,7 +69,7 @@ https://github.com/ESCOMP/ctsm/wiki #### Coding Practices and Style: -Code conventions: https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines +Code conventions: https://escomp.github.io/CTSM/dev_guide/clm-coding-conventions.html #### Code of Conduct: From acb2d3f18188f254c165039f50494a2487c7d865 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 13:47:11 -0600 Subject: [PATCH 32/59] Add bug report issue form. --- .github/ISSUE_TEMPLATE/01_bug_report.yml | 126 +++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/01_bug_report.yml diff --git a/.github/ISSUE_TEMPLATE/01_bug_report.yml b/.github/ISSUE_TEMPLATE/01_bug_report.yml new file mode 100644 index 0000000000..d9dc5ac19b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/01_bug_report.yml @@ -0,0 +1,126 @@ +name: Bug report +description: Report a problem with the code +labels: ["bug"] +type: Bug +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + + - type: textarea + id: brief-summary + attributes: + label: Brief summary of bug + description: Give a one or two sentence summary. This could be the same as the issue title if you feel that is a sufficient summary. There will be room to give additional details below. + validations: + required: true + + - type: markdown + attributes: + value: | + ### General bug information + + - type: input + id: version + attributes: + label: CTSM version you are using + description: Output of `git describe` + placeholder: "ctsmX.Y.ZZZ..." + validations: + required: true + + - type: dropdown + id: significant-incorrect-science + attributes: + label: Does this bug cause significantly incorrect results in the model's science? + options: + - "Yes" + - "No" + validations: + required: true + + - type: textarea + id: configs-affected + attributes: + label: Configurations affected + placeholder: Fill this in if known + validations: + required: false + + - type: markdown + attributes: + value: | + ### AI disclosure + + - type: dropdown + id: was-ai-used + attributes: + label: Was AI used in this contribution? + options: + - "Yes" + - "No" + validations: + required: true + + - type: input + id: ai-usage-details + attributes: + label: If you used AI, what did you use it for? (If not, put n/a.) + description: "For example: identifying bug; searching for related issues/PRs; providing minimal working example; drafting issue text" + validations: + required: true + + - type: textarea + id: how-confirmed-ai-bug + attributes: + label: If AI discovered this bug, how have you confirmed that it's real? (If not, put n/a.) + description: "Make sure that you as a human being understand the bug! If you don't, we may deprioritize responding to your submission, as we have had numerous instances where an LLM thought something was a bug and it turned out not to be." + validations: + required: true + + - type: input + id: ai-provider + attributes: + label: AI provider + placeholder: "E.g., Anthropic" + description: Optional + validations: + required: false + + - type: input + id: ai-model + attributes: + label: AI model + placeholder: "E.g., Opus 5.5 high effort" + description: Optional + validations: + required: false + + - type: markdown + attributes: + value: | + ### Details of bug + + - type: textarea + id: additional-detail + attributes: + label: Additional details + validations: + required: false + + - type: textarea + id: setup-details + attributes: + label: Important details of your setup / configuration so we can reproduce the bug + description: "Specify anything relevant: the compset, resolution, machine, compiler, any xml or namelist changes, etc. You don't have to repeat anything that you have already noted above." + validations: + required: false + + - type: textarea + id: output-or-errors + attributes: + label: Important output or errors that show the problem + description: Fill this in with anything relevant that you haven't already noted. + validations: + required: false From 9dba65ae5367129d28513d348fae6a9932abbda4 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 14:32:29 -0600 Subject: [PATCH 33/59] Add other issue forms. --- .../ISSUE_TEMPLATE/02_science_discussion.yml | 61 ++++++++++++ .github/ISSUE_TEMPLATE/03_documentation.yml | 95 +++++++++++++++++++ .github/ISSUE_TEMPLATE/04_other.yml | 59 ++++++++++++ AGENTS.md | 2 +- 4 files changed, 216 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/02_science_discussion.yml create mode 100644 .github/ISSUE_TEMPLATE/03_documentation.yml create mode 100644 .github/ISSUE_TEMPLATE/04_other.yml diff --git a/.github/ISSUE_TEMPLATE/02_science_discussion.yml b/.github/ISSUE_TEMPLATE/02_science_discussion.yml new file mode 100644 index 0000000000..e18a9eb3ec --- /dev/null +++ b/.github/ISSUE_TEMPLATE/02_science_discussion.yml @@ -0,0 +1,61 @@ +name: Science discussion +description: We encourage the use of issues to discuss CTSM science developments +labels: ["science", "enhancement"] +type: Feature +body: + + - type: textarea + id: brief-summary + attributes: + label: Brief summary + description: Give a one or two sentence summary. This could be the same as the issue title if you feel that is a sufficient summary. + validations: + required: true + + - type: textarea + id: further-details + attributes: + label: Further details + validations: + required: false + + - type: markdown + attributes: + value: | + ### AI disclosure + + - type: dropdown + id: was-ai-used + attributes: + label: Was AI used in this contribution? + options: + - "Yes" + - "No" + validations: + required: true + + - type: input + id: ai-usage-details + attributes: + label: If you used AI, what did you use it for? (If not, put n/a.) + description: "For example: understanding relevant parts of the codebase; outlining possible implementation; drafting issue text" + validations: + required: true + + - type: input + id: ai-provider + attributes: + label: AI provider + placeholder: "E.g., Anthropic" + description: Optional + validations: + required: false + + - type: input + id: ai-model + attributes: + label: AI model + placeholder: "E.g., Opus 5.5 high effort" + description: Optional + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/03_documentation.yml b/.github/ISSUE_TEMPLATE/03_documentation.yml new file mode 100644 index 0000000000..f8edc31e56 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/03_documentation.yml @@ -0,0 +1,95 @@ +name: Documentation +description: Something should be added to or fixed in the documentation +labels: ["documentation"] +type: Documentation +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this issue! If you're planning to eventually contribute a change, please see our [contribution guidelines for documentation](https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-intro.html#contribution-guidelines). + + - type: checkboxes + id: docs-issue-type + attributes: + label: What sort(s) of documentation issue is this? + description: You may select more than one. + options: + - label: Something is missing. + - label: Something is (or might be) incorrect or outdated. + - label: Something is confusing. + - label: Something is broken. + + - type: checkboxes + id: docs-location + attributes: + label: What part(s) of the documentation does this concern? + description: You may select more than one. + options: + - label: '[Technical Note](https://escomp.github.io/CTSM/tech_note/index.html) (science and design of the model)' + - label: "[User's Guide](https://escomp.github.io/CTSM/users_guide/index.html) (using the model and related tools)" + - label: "Somewhere else (e.g., README file, tool help text, or code comment)" + - label: "I don't know" + + - type: input + id: somewhere-else + attributes: + label: If "somewhere else," where? + validations: + required: false + + - type: textarea + id: describe-the-issue + attributes: + label: Describe the issue + description: A clear and concise description of what is missing or wrong. + validations: + required: true + + - type: textarea + id: additional-context + attributes: + label: Additional context + description: Add any other context or screenshots about the issue here. + validations: + required: false + + - type: markdown + attributes: + value: | + ### AI disclosure + + - type: dropdown + id: was-ai-used + attributes: + label: Was AI used in this contribution? + options: + - "Yes" + - "No" + validations: + required: true + + - type: input + id: ai-usage-details + attributes: + label: If you used AI, what did you use it for? (If not, put n/a.) + description: "For example: understanding relevant parts of the codebase and/or documentation; drafting suggested documentation changes; drafting issue text" + validations: + required: true + + - type: input + id: ai-provider + attributes: + label: AI provider + placeholder: "E.g., Anthropic" + description: Optional + validations: + required: false + + - type: input + id: ai-model + attributes: + label: AI model + placeholder: "E.g., Opus 5.5 high effort" + description: Optional + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/04_other.yml b/.github/ISSUE_TEMPLATE/04_other.yml new file mode 100644 index 0000000000..ab0887ec65 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/04_other.yml @@ -0,0 +1,59 @@ +name: Other +description: Other issues (enhancement, cleanup, etc.) +body: + + - type: textarea + id: brief-summary + attributes: + label: Brief summary + description: Give a one or two sentence summary. This could be the same as the issue title if you feel that is a sufficient summary. + validations: + required: true + + - type: textarea + id: further-details + attributes: + label: Further details + validations: + required: false + + - type: markdown + attributes: + value: | + ### AI disclosure + + - type: dropdown + id: was-ai-used + attributes: + label: Was AI used in this contribution? + options: + - "Yes" + - "No" + validations: + required: true + + - type: input + id: ai-usage-details + attributes: + label: If you used AI, what did you use it for? (If not, put n/a.) + description: "For example: understanding relevant parts of the codebase; outlining possible implementation; drafting issue text" + validations: + required: true + + - type: input + id: ai-provider + attributes: + label: AI provider + placeholder: "E.g., Anthropic" + description: Optional + validations: + required: false + + - type: input + id: ai-model + attributes: + label: AI model + placeholder: "E.g., Opus 5.5 high effort" + description: Optional + validations: + required: false diff --git a/AGENTS.md b/AGENTS.md index f97e6aba64..ce53fc1f1c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ Co-Authored-By: Claude Opus 5.5 "The CTSM repo" in this section specifically refers to the GitHub repo ESCOMP/CTSM, not forks. - **You may never submit, edit, or comment on an issue or PR in the CTSM repo** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. We consider it only fair that the contributing human do the same. -- You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. Then follow the repository templates: `.github/PULL_REQUEST_TEMPLATE.md` for PRs and the relevant template under `.github/ISSUE_TEMPLATE/` for issues. Preserve the template's sections and checklist, filling in or adapting placeholders as needed. +- You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. If drafting a PR,use the `.github/PULL_REQUEST_TEMPLATE.md`; preserve the template's sections and checklist, filling in or adapting placeholders as needed. - You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Whenever you or your human pushes changes to a PR branch, review the existing PR description and prompt your human to update it if and where necessary. Remember, you are not allowed to edit an issue or PR description. - Unless your user tells you otherwise, you are also allowed to push to branches in forks, including branches that have associated PRs in ESCOMP/CTSM. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. From 096ed27150c390c2afd49fb65cf425cdfd2fc029 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:00:54 -0600 Subject: [PATCH 34/59] Docs issue form: Add question about docs version. --- .github/ISSUE_TEMPLATE/03_documentation.yml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/03_documentation.yml b/.github/ISSUE_TEMPLATE/03_documentation.yml index f8edc31e56..46069944db 100644 --- a/.github/ISSUE_TEMPLATE/03_documentation.yml +++ b/.github/ISSUE_TEMPLATE/03_documentation.yml @@ -37,6 +37,14 @@ body: validations: required: false + - type: input + id: docs-version + attributes: + label: If in Technical Note and/or User's Guide, what version(s)? + description: See "Version:" menu in bottom left of documentation webpage + validations: + required: false + - type: textarea id: describe-the-issue attributes: From 3826095d33a9b1530efafecd567b6082c04e3a7b Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:01:31 -0600 Subject: [PATCH 35/59] Delete GitHub issue templates; use forms instead. --- .github/ISSUE_TEMPLATE/01_bug_report.md | 41 ------------------- .../ISSUE_TEMPLATE/02_science_discussion.md | 19 --------- .github/ISSUE_TEMPLATE/03_documentation.md | 34 --------------- .github/ISSUE_TEMPLATE/04_other.md | 19 --------- 4 files changed, 113 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/01_bug_report.md delete mode 100644 .github/ISSUE_TEMPLATE/02_science_discussion.md delete mode 100644 .github/ISSUE_TEMPLATE/03_documentation.md delete mode 100644 .github/ISSUE_TEMPLATE/04_other.md diff --git a/.github/ISSUE_TEMPLATE/01_bug_report.md b/.github/ISSUE_TEMPLATE/01_bug_report.md deleted file mode 100644 index d14ec4324c..0000000000 --- a/.github/ISSUE_TEMPLATE/01_bug_report.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: Bug report -about: Report a problem with the code - ---- - -### Brief summary of bug - -[Give a one or two sentence summary. This could be the same as the issue title if you feel that is a sufficient summary.] - -### General bug information - -**CTSM version you are using:** [output of `git describe`] - -**Does this bug cause significantly incorrect results in the model's science?** [Yes / No] - -**Configurations affected:** [Fill this in if known.] - -### AI disclosure - -- [ ] Was AI used in this contribution? **Yes/no**: - -If yes: - -- [ ] Types of work: - -- [ ] I have confirmed that this is a real bug. **How:** -- Provider (optional): -- Model (optional): - -### Details of bug - -[Fill in details here.] - -### Important details of your setup / configuration so we can reproduce the bug - -[Specify anything relevant: the compset, resolution, machine, compiler, any xml or namelist changes, etc. You don't have to repeat anything that you have already noted above.] - -### Important output or errors that show the problem - -[Fill this in with anything relevant that you haven't already noted; if there is nothing to add, delete this section.] diff --git a/.github/ISSUE_TEMPLATE/02_science_discussion.md b/.github/ISSUE_TEMPLATE/02_science_discussion.md deleted file mode 100644 index 15da0992f6..0000000000 --- a/.github/ISSUE_TEMPLATE/02_science_discussion.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -name: Science discussion -about: We encourage the use of issues to discuss CTSM science developments - ---- - -### Brief summary - -### Further details - -### AI disclosure - -- [ ] Was AI used in this contribution? **Yes/no**: - -If yes: - -- [ ] Types of work: -- Provider (optional): -- Model (optional): diff --git a/.github/ISSUE_TEMPLATE/03_documentation.md b/.github/ISSUE_TEMPLATE/03_documentation.md deleted file mode 100644 index a76db1d1f6..0000000000 --- a/.github/ISSUE_TEMPLATE/03_documentation.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: Documentation -about: Something should be added to or fixed in the documentation - ---- -(Please see our [contribution guidelines for documentation](https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-intro.html#contribution-guidelines).) - -### What sort(s) of documentation issue is this? -- [ ] Something is missing. -- [ ] Something is (or might be) incorrect or outdated. -- [ ] Something is confusing. -- [ ] Something is broken. - -### What part(s) of the documentation does this concern? -- [ ] [Technical Note](https://escomp.github.io/CTSM/tech_note/index.html) (science and design of the model) -- [ ] [User's Guide](https://escomp.github.io/CTSM/users_guide/index.html) (using the model and related tools) -- [ ] Somewhere else (e.g., README file, tool help text, or code comment): _Please specify_ -- [ ] I don't know - -### Describe the issue -A clear and concise description of what is missing or wrong. - -### Additional context (optional) -Add any other context or screenshots about the issue here. - -### AI disclosure - -- [ ] Was AI used in this contribution? **Yes/no**: - -If yes: - -- [ ] Types of work: -- Provider (optional): -- Model (optional): diff --git a/.github/ISSUE_TEMPLATE/04_other.md b/.github/ISSUE_TEMPLATE/04_other.md deleted file mode 100644 index ef97d4ff43..0000000000 --- a/.github/ISSUE_TEMPLATE/04_other.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -name: Other -about: Other issues (enhancement, cleanup, etc.) - ---- - -### Brief summary - -### Further details - -### AI disclosure - -- [ ] Was AI used in this contribution? **Yes/no**: - -If yes: - -- [ ] Types of work: -- Provider (optional): -- Model (optional): From 81c2a82313a59b46949dc8e8f60f70d5ee0812f8 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:20:20 -0600 Subject: [PATCH 36/59] clm-coding-conventions.md: Remove refs to clmtype. Co-Authored-By: Claude Fable 5.1 --- doc/source/dev_guide/clm-coding-conventions.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index 3cea60ebd6..38fe1cfc91 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -150,7 +150,7 @@ call BandDiagonal(bounds, -nlevsno, nlevgrnd, jtop(begc:endc), jbot(begc:endc), ``` - The important point here is that the lower and upper bounds are explicitly specified for the gridcell / landunit / col / pft dimension of all array arguments. This is important for threading to work properly. -- Even for local variables whose dimensions only go begc:endc, please explicitly specify the dimensions as above when passing the array to a subroutine. This will ensure that threading continues to work if the variable's dimensions change (e.g., if it is pulled into clmtype, and thus has dimensions that span the proc_bounds rather than the clump_bounds). +- Even for local variables whose dimensions only go begc:endc, please explicitly specify the dimensions as above when passing the array to a subroutine. This will ensure that threading continues to work if the variable's dimensions change (e.g., if it is changed to have dimensions that span the proc_bounds rather than the clump_bounds). (clm-conventions-rtm-example)= @@ -438,15 +438,13 @@ These conventions cover some of the more detailed aspects of CLM code design. It 1. If a variable is only used in one subroutine it should be local to that subroutine 2. If a variable is only local to one module then it is declared private to that module. 3. Public data for modules should be used sparingly. -3. Only data required for output to history files should be in clmtype.F90. -4. A separate restart module/subroutine called from CLM restFileMod.F90 should be used to facilitate reading/writing of information to restart files. -5. In general data initialized in clmtype should have a separate module/subroutine to do so. -6. The number of variables added to clmtype needs to be limited. +3. Model state and flux variables live in derived types defined in their own modules (e.g., `CropType.F90`). Add new variables to the relevant type rather than to shared global modules. +4. Derived types provide their own `Init`, `InitHistory`, `InitCold`, and `Restart` procedures as necessary. ### Guidelines for Fortran statements 1. Fortran2003 deprecated features will not be accepted in new code (equivalence, common blocks, block data, etc.). -2. Use statements – should nearly always use the **only** construct to define what variables are being used from a given module. The only case when this is not to be done, is when the list of variables is so long to make this unmanageable taking up more than 6 continue lines (for example with use of the clmtype module). +2. Use statements – should nearly always use the **only** construct to define what variables are being used from a given module. The only case when this is not to be done is when the list of variables is so long to make this unmanageable taking up more than 6 continue lines. 3. The "intent" attribute of subroutine input/output variables is used. Argument lists should ALWAYS use the INTENT attribute (try to have data be either IN or OUT and avoid INOUT if possible/reasonable). 4. Try to limit the use of the "use statement" to other modules to subroutines/functions and read-only parameters. 5. Data that is read-only, or output from a subroutine/function should be passed down using argument lists. From 8e39b2c357adf61a8392a4e5f495b77534b75153 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:21:39 -0600 Subject: [PATCH 37/59] PR template: Link to new coding conventions webpage. --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 80fc9b8591..ef300264b7 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,7 +1,7 @@ From 38b258a26a3f358f120065c041f9922fff2ae34b Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:24:30 -0600 Subject: [PATCH 38/59] clm-coding-conventions.md: Add link to CLM4.5 refactoring page. --- doc/source/dev_guide/clm-coding-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index 38fe1cfc91..5506c1d23a 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -383,7 +383,7 @@ type(bounds_type), intent(in) :: bounds ! bounds ### Preprocessor Macros (CPP Tokens) -- We are in the process of removing CPP Tokens from all of CLM (see our refactoring page ) and will not accept code using them. +- We are in the process of removing CPP Tokens from all of CLM (see [our refactoring page](https://wiki.ucar.edu/spaces/ccsm/pages/274339715/Recent+CLM4.5+Refactoring#RecentCLM4.5Refactoring-Preprocessormacroremovalmacro)) and will not accept code using them. ```{code-block} fortran :caption: Preprocessor Macros (CPP Tokens) - Do From 7e367d4483861cb3f95e7977f6f58d3694d3e7b2 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:25:13 -0600 Subject: [PATCH 39/59] clm-coding-conventions.md: Remove "previous page" ref. And fix a typo. Co-Authored-By: Claude Fable 5.1 --- doc/source/dev_guide/clm-coding-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index 5506c1d23a..1f60da5b49 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -411,7 +411,7 @@ type(bounds_type), intent(in) :: bounds ! bounds ## Comprehensive list of standards -These conventions cover some of the more detailed aspects of CLM code design. It is intended to compliment and extend the information found on the [previous page](#clm-coding-conventions). If you have questions please contact us at [ctsm-support@ucar.edu](mailto:ctsm-support@ucar.edu) or on your GitHub discussion, issue, or pull request. +These conventions cover some of the more detailed aspects of CLM code design. It is intended to complement and extend the information found above. If you have questions please contact us at [ctsm-support@ucar.edu](mailto:ctsm-support@ucar.edu) or on your GitHub discussion, issue, or pull request. ### General Guidelines From 060b3dd60a7d22ba05ada085889e230b422d00c5 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:26:16 -0600 Subject: [PATCH 40/59] clm-coding-conventions.md: Fix a contradictory .lt. --- doc/source/dev_guide/clm-coding-conventions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index 1f60da5b49..f5b1837d73 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -297,7 +297,7 @@ type(bounds_type), intent(in) :: bounds ! bounds ! maximum declination hardwired for present-day orbital parameters, ! ± 23.4667 degrees = ± 0.409571 radians, use negative value for S. Hem max_decl = 0.409571 - if (grc%lat(g) .lt. 0._r8) max_decl = -max_decl + if (grc%lat(g) < 0._r8) max_decl = -max_decl max_dayl(c) = calcMaxDayFunc( grc%lat(g) , max_decl ) ! From CanopyFluxesMod: @@ -324,7 +324,7 @@ type(bounds_type), intent(in) :: bounds ! bounds ! maximum declination hardwired for present-day orbital parameters, ! ± 23.4667 degrees = ± 0.409571 radians, use negative value for S. Hem max_decl = 0.409571 - if (grc%lat(g) .lt. 0._r8) max_decl = -max_decl + if (grc%lat(g) < 0._r8) max_decl = -max_decl temp = -(sin(grc%lat(g))*sin(max_decl))/(cos(grc%lat(g)) * cos(max_decl)) temp = min(1._r8,max(-1._r8,temp)) max_dayl(c) = 2.0_r8 * 13750.9871_r8 * acos(temp) From b7393e444116ae7f166065e2da3e3bc18ea02863 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:27:04 -0600 Subject: [PATCH 41/59] clm-coding-conventions.md: Remove `== .true` example Co-Authored-By: Claude Fable 5.1 --- doc/source/dev_guide/clm-coding-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index f5b1837d73..d716688ffb 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -389,7 +389,7 @@ type(bounds_type), intent(in) :: bounds ! bounds :caption: Preprocessor Macros (CPP Tokens) - Do ! do this: - if (useNewPhysics == .true.) then + if (useNewPhysics) then ... ! do some new physics ... From 37cafd8c1ebdc4eaf40ae7e2d751b798149d8daa Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:29:38 -0600 Subject: [PATCH 42/59] AGENTS.md: Try to soften contradiction about refs to plan docs --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ce53fc1f1c..0bf71814e9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,12 +3,12 @@ **Read and obey all standards described in `CONTRIBUTING.md`, including the webpage linked under "Coding Practices and Style," which you can also find in this repo at `doc/source/dev_guide/clm-coding-conventions.md`.** ## General rules -- You must assume that any development design or implementation plan documents will not be brought into the repository upon merge. It's fine to commit them and even open pull requests with them present, but the maintainers will require that you remove them before merge. Therefore, all work you do -- code comments, persistent documentation, commit messages -- must stand on their own without reference to those documents. +- You must assume that any development design or implementation plan documents will not be brought into the repository upon merge. It's fine to commit them and even open pull requests with them present, but the maintainers will require that you remove them before merge. Therefore, all work you do -- code comments, persistent documentation, commit messages -- must eventually stand on its own without reference to those documents. ## Commits - Commits must, as much as possible, do one "thing" and do it completely. It's fine for commits to work in multiple places across the codebase, if this is necessary to perform one coherent step of development. - The "headline" of commit messages must, as much as possible, be written in plain language that can be understood by someone familiar with CTSM but not necessarily with the issue being addressed. -- No part of any commit message may reference development plan documents without at least explaining the referent. E.g., "Task 2 Step 4" is not acceptable without saying what that *is* (e.g., "Separate xyz functionality into a separate subroutine). Ideally, though, such references would be stripped by rebasing before requesting review on a PR. +- No part of any commit message may reference development plan documents without at least explaining the referent. E.g., "Task 2 Step 4" is not acceptable without saying what that *is* (e.g., "Separate xyz functionality into a separate subroutine). Ideally, though, such references would be stripped by rebasing before requesting review on a PR, and as mentioned above the maintainers will at least require that you remove them before merge. That effort might be worth it to you and/or your human in the service of better tracking your work, but know that it will be effort. - Commit messages that you as an LLM write must include a "Co-Authored-By" credit at the end naming your model and version. This also applies to messages a human writes for commits containing *material* that you wrote -- make sure the human complies, or ask to reword commits to add it as necessary. For example: ``` Co-Authored-By: Claude Opus 5.5 From 60c883cc70796352ec5c57ad711f3caf806eced5 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:30:27 -0600 Subject: [PATCH 43/59] AGENTS.md: Delete a repetitive sentence. --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 0bf71814e9..3a51d99e94 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,7 +19,7 @@ Co-Authored-By: Claude Opus 5.5 - **You may never submit, edit, or comment on an issue or PR in the CTSM repo** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. We consider it only fair that the contributing human do the same. - You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. If drafting a PR,use the `.github/PULL_REQUEST_TEMPLATE.md`; preserve the template's sections and checklist, filling in or adapting placeholders as needed. -- You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Whenever you or your human pushes changes to a PR branch, review the existing PR description and prompt your human to update it if and where necessary. Remember, you are not allowed to edit an issue or PR description. +- You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Whenever you or your human pushes changes to a PR branch, review the existing PR description and prompt your human to update it if and where necessary. - Unless your user tells you otherwise, you are also allowed to push to branches in forks, including branches that have associated PRs in ESCOMP/CTSM. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. From 6b6611b66c6965e25361df0c0e5bd75b3d21c506 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:32:12 -0600 Subject: [PATCH 44/59] AGENTS.md: Better signal "example" for co-authored-by. Co-Authored-By: Claude Fable 5.1 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 3a51d99e94..c765f33ef9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ - Commits must, as much as possible, do one "thing" and do it completely. It's fine for commits to work in multiple places across the codebase, if this is necessary to perform one coherent step of development. - The "headline" of commit messages must, as much as possible, be written in plain language that can be understood by someone familiar with CTSM but not necessarily with the issue being addressed. - No part of any commit message may reference development plan documents without at least explaining the referent. E.g., "Task 2 Step 4" is not acceptable without saying what that *is* (e.g., "Separate xyz functionality into a separate subroutine). Ideally, though, such references would be stripped by rebasing before requesting review on a PR, and as mentioned above the maintainers will at least require that you remove them before merge. That effort might be worth it to you and/or your human in the service of better tracking your work, but know that it will be effort. -- Commit messages that you as an LLM write must include a "Co-Authored-By" credit at the end naming your model and version. This also applies to messages a human writes for commits containing *material* that you wrote -- make sure the human complies, or ask to reword commits to add it as necessary. For example: +- Commit messages that you as an LLM write must include a "Co-Authored-By" credit at the end naming your model and version. This also applies to messages a human writes for commits containing *material* that you wrote -- make sure the human complies, or ask to reword commits to add it as necessary. For example, if you are Claude Opus 5.5: ``` Co-Authored-By: Claude Opus 5.5 ``` From 3a91aa4a6d689b1ad7a0c41edf6f242882f5aea4 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:35:31 -0600 Subject: [PATCH 45/59] AGENTS.md: Use rebasing to remove (refs to) planning docs. --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index c765f33ef9..b5addbf6d5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,4 +22,4 @@ Co-Authored-By: Claude Opus 5.5 - You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Whenever you or your human pushes changes to a PR branch, review the existing PR description and prompt your human to update it if and where necessary. - Unless your user tells you otherwise, you are also allowed to push to branches in forks, including branches that have associated PRs in ESCOMP/CTSM. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. - +- When removing planning documents and references thereto, do so using rebase instead of extra commits. This simplifies the git history and prevents even the traces of unnecessary files from being brought into the repo. From 951c086a72112174dd71c312aea70e4dadfccae1 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:38:54 -0600 Subject: [PATCH 46/59] CONTRIBUTING.md: Add links to new issue, discussion pages. --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c552d9ee5b..38d8a763de 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ ## How to contribute: -We appreciate that you want to contribute to making CTSM better! Before you submit a pull request, however, we require that you first open an issue (https://github.com/escomp/ctsm/issues/) to -discuss the changes or additions that you propose. Through the issue discussion, you can +We appreciate that you want to contribute to making CTSM better! Before you submit a pull request, however, we require that you first open a [GitHub issue](https://github.com/ESCOMP/CTSM/issues/new/choose) or [GitHub discussion](https://github.com/ESCOMP/CTSM/discussions/new/choose) to +discuss the changes or additions that you propose. That way, you can work with other CTSM developers to think about the design and implementation of the changes as well as the planning and scheduling for the change to come into CTSM. Making contact early in your project will increase the likelihood that your developments can come From 0b07c9da7e0607bd8e361e332eb49ed489ecacb9 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:39:33 -0600 Subject: [PATCH 47/59] clm-coding-conventions.md: Fix a reference --- doc/source/dev_guide/clm-coding-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/dev_guide/clm-coding-conventions.md b/doc/source/dev_guide/clm-coding-conventions.md index d716688ffb..3203e888fb 100644 --- a/doc/source/dev_guide/clm-coding-conventions.md +++ b/doc/source/dev_guide/clm-coding-conventions.md @@ -419,7 +419,7 @@ These conventions cover some of the more detailed aspects of CLM code design. It 2. Use **implicit none**. All variables must be explicitly typed. 3. **Don't repeat yourself**. Duplicated code is difficult to maintain. If you find yourself using copy and paste more than once, create a new function or subroutine that encapsulates the desired functionality. 4. Try to implement subroutine and function interface with argument lists of 9 or less. If you have lists longer than this, break up the functionality into multiple methods and/or use derived types for higher level interfaces. Try to have argument lists short enough that you can make unit-tests for them. -5. If you have argument lists greater than 8 -- you must call such routines using the keyword-pair form for all arguments (but see 3 above). +5. If you have argument lists greater than 8 -- you must call such routines using the keyword-pair form for all arguments (but see 4 above). ### Performance, debugging and optimization From 60ece9174788baf03c72c12753c45643a5b528a7 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 17:41:26 -0600 Subject: [PATCH 48/59] AGENTS.md: Typo fix --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b5addbf6d5..aa65a3d3a2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,8 +17,8 @@ Co-Authored-By: Claude Opus 5.5 ## GitHub issues and pull requests "The CTSM repo" in this section specifically refers to the GitHub repo ESCOMP/CTSM, not forks. -- **You may never submit, edit, or comment on an issue or PR in the CTSM repo** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. We consider it only fair that the contributing human do the same. -- You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. If drafting a PR,use the `.github/PULL_REQUEST_TEMPLATE.md`; preserve the template's sections and checklist, filling in or adapting placeholders as needed. +- **You may never submit, edit, or comment on an issue or PR in the CTSM repo.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. We consider it only fair that the contributing human do the same. +- You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. If drafting a PR, use the `.github/PULL_REQUEST_TEMPLATE.md`; preserve the template's sections and checklist, filling in or adapting placeholders as needed. - You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Whenever you or your human pushes changes to a PR branch, review the existing PR description and prompt your human to update it if and where necessary. - Unless your user tells you otherwise, you are also allowed to push to branches in forks, including branches that have associated PRs in ESCOMP/CTSM. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. From 302dd9a899a9768906ede54cedaedf3dbc53b8d5 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 18:27:39 -0600 Subject: [PATCH 49/59] AGENTS.md: Explain what to do if if human asks AI to do GitHub stuff. --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index aa65a3d3a2..324557eab8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,7 @@ Co-Authored-By: Claude Opus 5.5 "The CTSM repo" in this section specifically refers to the GitHub repo ESCOMP/CTSM, not forks. - **You may never submit, edit, or comment on an issue or PR in the CTSM repo.** The maintainers are humans who will take the time and care to use their human brains to work with the contributing human. We consider it only fair that the contributing human do the same. +- If prompted to submit, comment on, or edit an issue or PR on the CTSM repo, decline and explain that maintainer interactions must be conducted directly by the human contributor, but offer to draft or refine the text locally. - You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. If drafting a PR, use the `.github/PULL_REQUEST_TEMPLATE.md`; preserve the template's sections and checklist, filling in or adapting placeholders as needed. - You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Whenever you or your human pushes changes to a PR branch, review the existing PR description and prompt your human to update it if and where necessary. - Unless your user tells you otherwise, you are also allowed to push to branches in forks, including branches that have associated PRs in ESCOMP/CTSM. From fedddf268a1257794befe3343f381b0b01de1fc4 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 18:27:55 -0600 Subject: [PATCH 50/59] AGENTS.md: Add Co-Authored By example for Gemini. --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 324557eab8..de7e7371d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,10 @@ ``` Co-Authored-By: Claude Opus 5.5 ``` +Or if you are, e.g., Gemini 3.8 Flash: +``` +Co-Authored-By: Gemini 3.8 Flash +``` ## GitHub issues and pull requests "The CTSM repo" in this section specifically refers to the GitHub repo ESCOMP/CTSM, not forks. From 4469ada4d705d05db4a4a8a4f2435f118487d59e Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 18:29:40 -0600 Subject: [PATCH 51/59] CONTRIBUTING.md: Clarify that AI usage example is PR template. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 38d8a763de..fbeaf8dbdd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,7 +48,7 @@ You must be able to explain why the changes are correct, how they fit CTSM, and **Do not delegate conversations with maintainers to an agent.** The maintainers of this repo are human beings who will use their human brains to review every single line of your contribution. Please show them the same courtesy when discussing an issue or PR. -Every issue and PR must state whether generative AI was used in preparing the contribution, including research, code, tests, documentation, or language assistance. If AI was used, briefly describe how it was used; this description is required. Provider and model are optional. Keep the disclosure current as the PR changes, even if generated material was subsequently rewritten. Ordinary formatters, compilers, and test runners do not require AI disclosure. For example: +Every issue and PR must state whether generative AI was used in preparing the contribution, including research, code, tests, documentation, or language assistance. If AI was used, briefly describe how it was used; this description is required. Provider and model are optional. Keep the disclosure current as the PR changes, even if generated material was subsequently rewritten. Ordinary formatters, compilers, and test runners do not require AI disclosure. For example, on PRs: > - [x] Was AI used in this contribution? **Yes**: > If yes: From 7e24ef5c66cb2cd779f66241d9e5d09dd6760d45 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 18:34:03 -0600 Subject: [PATCH 52/59] AGENTS.md: Add instructions for non-interactive rebase. Co-Authored-By: Gemini 3.8 Flash --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index de7e7371d7..db25d7eb2a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,4 +27,4 @@ Co-Authored-By: Gemini 3.8 Flash - You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Whenever you or your human pushes changes to a PR branch, review the existing PR description and prompt your human to update it if and where necessary. - Unless your user tells you otherwise, you are also allowed to push to branches in forks, including branches that have associated PRs in ESCOMP/CTSM. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. -- When removing planning documents and references thereto, do so using rebase instead of extra commits. This simplifies the git history and prevents even the traces of unnecessary files from being brought into the repo. +- When removing planning documents and references thereto, do so using rebase or `git reset --soft` instead of extra commits. If rebasing, you may need to do so non-interactively (e.g., using `git reset --soft`, `--no-edit`, or `GIT_SEQUENCE_EDITOR=:`) to avoid hanging in non-TTY environments. This simplifies the git history and prevents even the traces of unnecessary files from being brought into the repo. From 354a7656619679bd18ad28c9a935ca1b1fe892f8 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 18:36:08 -0600 Subject: [PATCH 53/59] CONTRIBUTING.md: Delete a stray colon --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fbeaf8dbdd..a6528636fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,7 +50,7 @@ You must be able to explain why the changes are correct, how they fit CTSM, and Every issue and PR must state whether generative AI was used in preparing the contribution, including research, code, tests, documentation, or language assistance. If AI was used, briefly describe how it was used; this description is required. Provider and model are optional. Keep the disclosure current as the PR changes, even if generated material was subsequently rewritten. Ordinary formatters, compilers, and test runners do not require AI disclosure. For example, on PRs: -> - [x] Was AI used in this contribution? **Yes**: +> - [x] Was AI used in this contribution? **Yes** > If yes: > - [x] Types of work: Designing changes, writing tests. > - Provider (optional): Anthropic From 80a77dc3a45b360db98f316f08571d3d0243f849 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 18:40:30 -0600 Subject: [PATCH 54/59] AGENTS.md: PRs: Never check boxes on human's behalf. Co-Authored-By: Gemini 3.8 Flash <200291788+gemini-code-assist@users.noreply.github.com> --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index db25d7eb2a..121a81024c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,5 +26,6 @@ Co-Authored-By: Gemini 3.8 Flash - You *are* allowed to help draft issues and PRs. If doing so, first read the standards described under the AI section in `CONTRIBUTING.md`. Make sure the human user understands and follows these rules during the contribution process. If drafting a PR, use the `.github/PULL_REQUEST_TEMPLATE.md`; preserve the template's sections and checklist, filling in or adapting placeholders as needed. - You are also allowed to read issues and PRs in the CTSM repo, including ones your human submits. Whenever you or your human pushes changes to a PR branch, review the existing PR description and prompt your human to update it if and where necessary. - Unless your user tells you otherwise, you are also allowed to push to branches in forks, including branches that have associated PRs in ESCOMP/CTSM. +- When drafting a PR description, leave the checkboxes under "Requirements before merge" unchecked (`- [ ]`) unless your human has explicitly confirmed to you that a given requirement is satisfied. Never check these boxes on your human's behalf. - Contributions (both issues and pull requests) often have implications for our documentation. You must ensure that our documentation has been reviewed for such implications and that these are accounted for in the contribution. Our documentation is mostly at `doc/source/`; make sure to look at the "documentation documentation" at `doc/source/users_guide/working-with-documentation/`. Also consider in-code documentation (docstrings, type annotations, and comments) as well as READMEs. - When removing planning documents and references thereto, do so using rebase or `git reset --soft` instead of extra commits. If rebasing, you may need to do so non-interactively (e.g., using `git reset --soft`, `--no-edit`, or `GIT_SEQUENCE_EDITOR=:`) to avoid hanging in non-TTY environments. This simplifies the git history and prevents even the traces of unnecessary files from being brought into the repo. From 2b0bce784d2a5a34b15a209545255a45cdc9dcab Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 18:42:21 -0600 Subject: [PATCH 55/59] CONTRIBUTING.md: Explain checkboxes --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a6528636fa..c0cdaff918 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,7 +48,7 @@ You must be able to explain why the changes are correct, how they fit CTSM, and **Do not delegate conversations with maintainers to an agent.** The maintainers of this repo are human beings who will use their human brains to review every single line of your contribution. Please show them the same courtesy when discussing an issue or PR. -Every issue and PR must state whether generative AI was used in preparing the contribution, including research, code, tests, documentation, or language assistance. If AI was used, briefly describe how it was used; this description is required. Provider and model are optional. Keep the disclosure current as the PR changes, even if generated material was subsequently rewritten. Ordinary formatters, compilers, and test runners do not require AI disclosure. For example, on PRs: +Every issue and PR must state whether generative AI was used in preparing the contribution, including research, code, tests, documentation, or language assistance. If AI was used, briefly describe how it was used; this description is required. Provider and model are optional. Keep the disclosure current as the PR changes, even if generated material was subsequently rewritten. Ordinary formatters, compilers, and test runners do not require AI disclosure. For example, on PRs, where the leading checkboxes indicate that the line has been filled out: > - [x] Was AI used in this contribution? **Yes** > If yes: From f74c5c99a3ca46d0d164dd9b92c01d8a029f5521 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 30 Oct 2026 18:53:53 -0600 Subject: [PATCH 56/59] AGENTS.md: Correct email address for Gemini. --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 121a81024c..9afe9457f6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,9 +13,9 @@ ``` Co-Authored-By: Claude Opus 5.5 ``` -Or if you are, e.g., Gemini 3.8 Flash: +Or if you are, e.g., Gemini 3.8 Flash (see [this gist section](https://gist.github.com/jyxjjj/290633474bee424050964f283f8b57a6#google-gemini) for email address options, but always specify your model version as the "user" name): ``` -Co-Authored-By: Gemini 3.8 Flash +Co-Authored-By: Gemini 3.8 Flash <200291788+gemini-code-assist@users.noreply.github.com> ``` ## GitHub issues and pull requests From 7395179d480bda92848db98c4d4e2e027aa0cd38 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 2 Nov 2026 13:59:22 -0700 Subject: [PATCH 57/59] AGENTS.md: Clarify that link for GEMINI emails. --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 9afe9457f6..766a403cef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,7 @@ ``` Co-Authored-By: Claude Opus 5.5 ``` -Or if you are, e.g., Gemini 3.8 Flash (see [this gist section](https://gist.github.com/jyxjjj/290633474bee424050964f283f8b57a6#google-gemini) for email address options, but always specify your model version as the "user" name): +Or if you are, e.g., Gemini 3.8 Flash (see [this gist section](https://gist.github.com/jyxjjj/290633474bee424050964f283f8b57a6#google-gemini) for more Gemini email address options, but always specify your model version as the "user" name): ``` Co-Authored-By: Gemini 3.8 Flash <200291788+gemini-code-assist@users.noreply.github.com> ``` From 4c4329982c8a7c8b82d0b1333605c34d6712ea1f Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 2 Nov 2026 14:03:30 -0700 Subject: [PATCH 58/59] AGENTS.md: Add a missing close quote --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 766a403cef..fa665443cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ ## Commits - Commits must, as much as possible, do one "thing" and do it completely. It's fine for commits to work in multiple places across the codebase, if this is necessary to perform one coherent step of development. - The "headline" of commit messages must, as much as possible, be written in plain language that can be understood by someone familiar with CTSM but not necessarily with the issue being addressed. -- No part of any commit message may reference development plan documents without at least explaining the referent. E.g., "Task 2 Step 4" is not acceptable without saying what that *is* (e.g., "Separate xyz functionality into a separate subroutine). Ideally, though, such references would be stripped by rebasing before requesting review on a PR, and as mentioned above the maintainers will at least require that you remove them before merge. That effort might be worth it to you and/or your human in the service of better tracking your work, but know that it will be effort. +- No part of any commit message may reference development plan documents without at least explaining the referent. E.g., "Task 2 Step 4" is not acceptable without saying what that *is* (e.g., "Separate xyz functionality into a separate subroutine"). Ideally, though, such references would be stripped by rebasing before requesting review on a PR, and as mentioned above the maintainers will at least require that you remove them before merge. That effort might be worth it to you and/or your human in the service of better tracking your work, but know that it will be effort. - Commit messages that you as an LLM write must include a "Co-Authored-By" credit at the end naming your model and version. This also applies to messages a human writes for commits containing *material* that you wrote -- make sure the human complies, or ask to reword commits to add it as necessary. For example, if you are Claude Opus 5.5: ``` Co-Authored-By: Claude Opus 5.5 From abe8f452bd3b4de3e2db843645c490f52f782ae8 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 2 Nov 2026 14:22:46 -0700 Subject: [PATCH 59/59] AGENTS.md: Add Co-Authored-By for ChatGPT Co-Authored-By: ChatGPT 5.6 Terra <267193182+codex@users.noreply.github.com> --- AGENTS.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index fa665443cc..b5471a78ff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,11 @@ Or if you are, e.g., Gemini 3.8 Flash (see [this gist section](https://gist.gith ``` Co-Authored-By: Gemini 3.8 Flash <200291788+gemini-code-assist@users.noreply.github.com> ``` +Or if you are, e.g., ChatGPT 5.6 Terra (see [this gist section](https://gist.github.com/jyxjjj/290633474bee424050964f283f8b57a6#openai-chatgpt--codex) for more ChatGPT email address options, but always specify your model version as the "user" name): +``` +Co-Authored-By: ChatGPT 5.6 Terra <267193182+codex@users.noreply.github.com> +``` +Make sure you customize the Co-Authored-By to match your model name and version, and always confirm the associated email address is real! That linked gist can be helpful, but use the email address given in your model docs if provided. ## GitHub issues and pull requests "The CTSM repo" in this section specifically refers to the GitHub repo ESCOMP/CTSM, not forks.