, 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.

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

...

• BFB (bit-for-bit)

  • New code produces results which are bit-for-bit identical with old code

  • Does not contain stealth features

  • github PR label: BFB

• Roundoff

  • New code would match old code in exact arithmetic, but will diverge exponentially fast when using finite precision

  • Climate of new and old code will converge as the averaging time goes to infinity

  • github PR label: non-BFB

• Climate changing

  • New feature is brought into the model turned on

  • Other model configuration change (parameters, resolution, forcing data)

  • github PR label: CC

• Stealth Feature

  • BFB code change that includes a new feature, turned off by default, or modifications to an existing stealth feature.

  • github PR labels: BFB and Stealth

...

• 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

...