, 2022/4/8: Original
2022/6/17: Revised to stress importance of not bundling features in a single PR
2022/8/31: Revised to remove duplicate terminology section
2023/4/18: Revised to clarify that modifications to an existing stealth feature is considered a stealth feature.
2023/5/18: Clarify that breaking the addition of a single feature into multiple PRs is welcome

This document describes the policy for bringing in new features and changing existing code in the E3SM model. This new policy requires a significant amount of work improving the E3SM diagnostics, CIME test suites and developing documentation, collected /wiki/spaces/CNCL/pages/3315138566

...

• Coupled model: B-case runs (~100 years) for WC, cryosphere and BGC configurations

• Component models: F, I and G cases, typically much shorter (e.g. 5 year F case with cyclic year 2010 forcing)

• Updated periodically when climate changes are integrated, or monthly ( to check for unintended changes)

• New features will be evaluated with respect to these reference solutions, with documentation on the import metrics

Note: E3SM Reference solutions and related documentation not yet ready!

Section 1: New Feature Request Process and Documentation Requirements

...

Externally funded work: developers are encouraged to submit this document early in their development process. This will assist with later E3SM acceptance.

1. Before writing code: Complete Proposer completes the New Feature Overview Document. Include, as appropriate:

   1. High-level description of code changes and/or new code, an overview of the design, infrastructure changes

   2. Expected improvements and how these will be demonstrated

   3. Describe needed updates to E3SM documentation

   4. Expected impacts on computational performance and mass/energy budgets.

   5. If relevant: describe papers that will be published

2. Before writing code: Document Review:

   Reviewed by

   Reviewer within E3SM (component lead or their delegate

   . Reviewer

   ) should:

   1. Review document for completeness

   2. Determine if there is sufficient benefit to E3SM to justify the E3SM integration and future maintenance costs.

      1. For features not needed by the E3SM SFA, but which may be needed to support other DOE BER missions, the component lead should consult with E3SM leadership.

   3. Determine if review by performance and infrastructure groups if needed and ensure they are done.

      1. discourage and/or flag use of advanced language features or unnecessary complexity that may not be supported well by compilers or may cause performance degradation

   4. Create one confluence page per document to allow for discussion during the review process

      1. Confluence space for all new feature overview documents and their approval status.

3. After new feature is approved, begin work in an E3SM fork, following Development Getting Started Guide

   1. Features which are not approved but are needed for other reasons can be maintained by the developer on their E3SM fork.

   2. Large new features should be developed through a series of PRs rather than a single massive PR (which would be hard to thoroughly test and scrutinize). One New Feature Overview Document can be used for all PRs associated with that feature.

4. When work is completed:

   1. Revise overview document to show improvements as originally proposed in overview document, and document simulation results from new feature PR guidelines. Include links to as yet to be constructed results archiving system (once it is ready)

   2. Submit PR PRs with links to documentation, follow new feature PR process.

...