...

Section 1: New Feature Request Process and Documentation Requirements

For new features

...

or other major code changes, prepare a New Feature Overview Document. To determine when a code change becomes a major code change, consult with the component lead.

E3SM-SFA funded work: feature should appear in that group’s roadmap before starting any work on a new feature including documentation prep. (E3SM pre-processing code (compsets, cime) and infrastructure are also covered by these procedures - infrastructure group is the “component group” for this work)

...

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

   1. high 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:

   1. Reviewed by 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.

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

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

...

BFB: no additional documentation is needed.

Roundoff. The developer must:

...