Home

Welcome to the MPAS-Model wiki!

Developer's Guide

Our general development philosophy is as follows:

• Do no harm. In general, this means that we do not change NCAR-developed/maintained code unless absolutely necessary. We'd love to fix some typos and change some indenting options, too, but doing so adds to the code reconciliation we must do every time we update to the top of their trunk (currently the main MPAS-Dev/MPAS-Model repository).
• New functionality should be user-controllable, and off by default. We love adding new functionality to the model and to our physics parameterizations. We believe that this should be namelist-controllable, with a corresponding entry in the appropriate Registry.xml file, and turned off by default (i.e., users must opt-in to the new functionality). In addition to giving users more control, this also ensures that our regression tests run on each new development do not fail solely because the new option is enabled.
• Mandatory regression testing. We have a basic regression-test suite available in the barlage/mpas_testcase repository, with instructions available upon request. Running these tests twice for each new PR is mandatory: a subset at initial submission and the full suite when the PR reaches the top of the queue and is otherwise ready to merge. This helps to ensure that code that is not expected to change answers does not do so and that code that is expected to change answers does so.
• One major change per PR. In general, we prefer that each PR be limited to a single major change rather than lumping multiple major changes into a single PR. This helps to facilitate its testing in our real-time development forecast systems and expedite its review.

Code Versioning We version our code in the format a.b(.c)-d.e, where a.b(.c) refers to the release at the top of the MPAS-Dev/MPAS-Model 'master' branch (v8.2.2 at the time of this writing in May 2025) and d.e refers to the internal version. 'd' is the major increment and is reserved for major new code functionality, whereas 'e' is the minor increment and is used for smaller, more iterative changes. Each new merged PR increments at least the minor increment. Incrementing the major increment resets the smaller increment, and updating the base version from MPAS-Dev/MPAS-Model resets both major and minor increments. The code version is applied in three locations: README.md, src/core_atmosphere/Registry.xml, and src/core_init_atmosphere/Registry.xml. Incrementing the code version is the last commit made to a PR; you should not increment your version number until your PR has completed review and is otherwise ready to merge.

Questions? Please don't hesitate to reach out to us with any questions, comments, or concerns that you may have. Thank you for your assistance and contributions!