Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
68 lines (52 loc) · 3.79 KB

CONTRIBUTING.md

File metadata and controls

68 lines (52 loc) · 3.79 KB
Raw

The Earth System Modeling Framework (ESMF) is high-performance, flexible software infrastructure for building and coupling weather, climate, and related Earth science applications. Please review the following guidelines for contributing to the Earth System Modeling Framework.

Resources

  • ESMF User Guide - html, pdf
  • Fortran Reference Manual - html, pdf
  • C Reference Manual - html, pdf
  • NUOPC Reference Manual - html, pdf
  • ESMPy Documentation - html, pdf
  • Developer’s Guide - html (Outdated! Use with caution. Ask if unsure.)

Development Platform

ESMF development can be performed using Dev Containers, which provide a consistent development environment across different machines. To use ESMF Dev Containers, see the documentation in .devcontainer/README.md for setup and usage instructions.

Submitting a pull request

  1. Fork and clone the repository
  2. Create a new branch: git checkout -b my-branch-name
  3. Make and test your changes
  4. Update documentation
  5. Push to your fork
  6. Execute ESMF CI and ESMF Docs from your fork on your branch using actions
  7. Compare across forks and submit a pull request

Testing

Pull requests must pass the ESMF CI action before they are accepted into the develop branch. The ESMF CI action is configured to test ESMF on a variety of configurations. These include multiple operating systems, MPI libraries, compilers, and build options. Prior to executing the ESMF CI action, changes should pass make all_tests on a local machine or HPC.

Documentation

ESMF uses LaTeX and LaTeX extensions to build inline documentation. Documentation can be built using the ESMF Docs action, which provides all the software needed to build documentation. Documentation can also be built locally using texlive-full and latex2html. ESMPY also requires the following Python packages: sphinx, sphinxcontrib-packages and sphinxcontrib-bibtex.

  • ESMF Documentation cd ${ESMF_DIR} && make doc
  • ESMF Developers Guide: cd ${ESMF_DIR}/src/doc/dev_guide && make
  • NUOPC Documentation cd ${ESMF_DIR}/src/addon/NUOPC/doc && make localdoc
  • ESMPY Documentation cd ${ESMF_DIR}/src/addon/esmpy && . ${PYTHON_VENV_ACTIVATE} && python3 -m pip install . && cd doc && . ${PYTHON_VENV_ACTIVATE} && make html latexpdf

Contact Us

ESMF Discussions is a GitHub Discussions forum for publicly discussing ESMF concerns and requests. For more information please see the ESMF Discussions How-To Guide.

If you do not have a GitHub Account, if you have privacy concerns posting to ESMF Discussions, or if you prefer communication via email then please contact esmf_support@ucar.edu.

Thank You,
The ESMF Core Team