Developing E3SM

The goal of the E3SM Code Development Process is to achieve high developer productivity while improving the Energy Exascale Earth system model. A degree of formality is needed because of the large size of the E3SM team, its geographic distribution, 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

Detailed instructions are available to our collaborators. Code should be of high enough quality to be readable, modifiable, and maintainable by others.

(from github) Check out the code or create a fork and then check out the code.

(on your development platform) Create a branch from master or a maintenance branch as appropriate. Your github user name should start the branch name.

Commit your changes to the branch in logical units.

Run the e3sm_developer test suite while developing your feature.

DO NOT MERGE FROM MASTER.

Run e3sm_developer again when you are finished. All tests should pass.

Push your finished branch to github.

(on github) make a Pull Request to add your feature.

Every feature should be developed on its own branch from master. Ideally, branches should contain code development that are is enough to be relevant to others, but simple enough that it can be called one feature (or perhaps a couple of highly-interdependent features). You may want to make a series of branches to complete your work.

For eventual inclusion of a new feature or algorithm into the E3SM Model, documents for the E3SM Code Review process should be created:

A design document (or paper) detailing the equations/algorithms that are being implemented

Verification evidence that supports that the implementation is correct

Performance analysis and data showing the expected and measured performance impact of the new feature