Developing E3SM

The goal of the E3SM Code Development Process is to achieve high developer productivity towards the improvement of the Energy Exascale Earth system model. A degree of formality is needed because of the large size of the E3SM team, the geographic distribution of the team, and large scope of the E3SM project, particularly when including collaborations.

E3SM development workflow uses Git with topic branches and pull requests.   We use a modified version of gitworkflows(7)

Basic steps of the E3SM code development process

  1. Code development should begin from the head of the master branch or most recent release branch of E3SM from the github repository
  2. Code should be of high enough quality to be readable, modifiable, and maintainable by others.
  3. Code development should follow E3SM procedures for using git.  We use a simplified version of the master/next workflow used by the Linux kernel developers. This allows parallel development of multiple features at the same time while preserving a stable master branch. The model is explained in gitworkflows(7) (but we do not currently use a pu branch).
  4. Developers must run the E3SM test suite to verify that their development has not unintentionally changed the code behavior, and all new development must be accompanied by tests to protect the new feature against future developments.
  5. Every feature should be developed on its own branch from master.   Ideally, feature branches are short-lived but if you have long running development do not merge from master just to keep up.
  6. For eventual inclusion of a new feature or algorithm into the E3SM Model, documents for the  E3SM Code Review process should be created:
    1. A design document (or paper) detailing the equations/algorithms that are being implemented
    2. Verification evidence that supports that the implementation is correct
    3. Performance analysis and data showing the expected and measured performance impact of the new feature
    4. Validation evidence that the feature matches observational data

Send this to a friend