Skip to main content
U.S. flag

An official website of the United States government

Publication Date
9 June 2023

E3SM: Reminder About the Practice of Open Development

Image
|
Description

Over the years, the E3SM project has developed a set of Best Practices for model development, running simulations, and doing standard data analysis. Every E3SM staff member or E3SM user is expected to follow those practices. As the project is now in the third funding phase, it is good to remind everyone of one of the guiding practices, namely, open-source development.

Early in the project, in April 2018, when E3SM version 1.0 was released, the project decided on the practice of open-source development. This practice was adopted following the recommendation of the Open Development Deep Dive Committee, which was composed of several E3SM Council Members. From this point on, the source code of E3SM was available to anyone. This included not only released versions but also the constantly changing main branch of code containing developments for the next release. The process of creating the next version of E3SM is visible to anyone with an internet connection. Note that we strongly advise that external users only use a released version (or their equivalent on a “maintenance branch”) for doing science with E3SM. The main branch is unstable and not validated!

E3SM was the first major climate model to pursue open development and we are proud to see other modeling groups adopt a similar practice.

The open development principle also applies to code that is under development by E3SM project members and not yet merged into the main branch. Developers begin their work by making a clone of the repository on their local machine or in their personal directory at one of the HPC centers. They then create a feature branch and begin development. To be consistent with E3SM’s best practice guidelines, all E3SM developers should “push” their branch after the first commit and keep updating the branch on GitHub as commits are added to the branch.

Besides following our open development policy, this allows colleagues and Group Leads to follow the work. Group Leads need that kind of visibility as they track progress on epics and tasks. It also makes it possible to find bugs before a pull request is made, as proposed in “Linus’s Law” which says, “given enough eyeballs, all bugs are shallow”. Open development also aligns with long-standing scientific principles of openness and collegiality.

Open Development Best Practice Principles:

  • All code should be shared openly through Github, either on your fork of E3SM or the main repository.
  • Push your branches to GitHub after you make commits.
  • Long-term development on a private branch is discouraged.

Refer to the E3SM user “Development Getting Started Guide” for specific practices when developing code for E3SM (any code, data analysis, and tools included, should follow the general practice described there, of using feature branches, pull requests, and merging)

For external users, the project would like to remind everyone that although the code’s full development progress is available to everyone, the only supported versions of the E3SM code are the code versions that were used for the target simulations, i.e the model releases: v1.0, 1.1, 2.0, 2.1. A user can get maintenance versions of these releases, with up-to-date build options on new computers, on the maintenance branches, maint-1.0, maint-1.1, etc. We have a guide for how to acknowledge E3SM in your work.

Resources

Funding Program Area(s)