From 9d480f784f868fd73eaed7b4912d0418cdfadfc6 Mon Sep 17 00:00:00 2001 From: Daniel Rosen Date: Mon, 7 Jul 2025 11:26:28 -0600 Subject: [PATCH 1/2] Add contributing documentation --- CONTRIBUTING.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..0ca0a554ef --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +The [Earth System Modeling Framework](https://earthsystemmodeling.org/) (ESMF) is high-performance, flexible software infrastructure for building and coupling weather, climate, and related Earth science applications. + +[fork]: https://github.com/esmf-org/esmf/fork +[pr]: https://github.com/esmf-org/esmf/compare +[actions]: https://github.com/esmf-org/esmf/actions + +## Resources + +* ESMF User Guide - [html](https://earthsystemmodeling.org/docs/nightly/develop/ESMF_usrdoc), [pdf](https://earthsystemmodeling.org/docs/nightly/develop/ESMF_usrdoc.pdf) +* Fortran Reference Manual - [html](https://earthsystemmodeling.org/docs/nightly/develop/ESMF_refdoc), [pdf](https://earthsystemmodeling.org/docs/nightly/develop/ESMF_refdoc.pdf) +* C Reference Manual - [html](https://earthsystemmodeling.org/docs/nightly/develop/ESMC_crefdoc), [pdf](https://earthsystemmodeling.org/docs/nightly/develop/ESMC_crefdoc.pdf) +* NUOPC Reference Manual - [html](https://earthsystemmodeling.org/docs/nightly/develop/NUOPC_refdoc), [pdf](https://earthsystemmodeling.org/docs/nightly/develop/NUOPC_refdoc.pdf) +* ESMPy Documentation - [html](https://earthsystemmodeling.org/esmpy_doc/nightly/develop/html), [pdf](https://earthsystemmodeling.org/esmpy_doc/nightly/develop/ESMPy.pdf) +* Developer’s Guide - [html](https://earthsystemmodeling.org/docs/nightly/develop/dev_guide) + +## Submitting a pull request + +1. [Fork][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][actions] +7. Compare across forks and [Submit a pull request][pr] + +## Testing + +Pull requests must pass the [ESMF CI][actions] action before they are accepted into the `develop` branch. The [ESMF CI][actions] 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][actions] action, changes should pass `make all_tests` on a local machine or HPC. + +## Documentation + +ESMF uses LaTeX and LaTeX extensions to build documentation. Documentation can be built using the [ESMF Docs][actions] action. 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` + +## Coding conventions + +* Indent using two spaces + +## Contact Us +[ESMF Discussions](https://github.com/orgs/esmf-org/discussions) is a GitHub Discussions forum for publicly discussing ESMF concerns and requests. For more information please see the [ESMF Discussions How-To Guide](https://github.com/orgs/esmf-org/discussions/246). + +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 From 0fe6d7a5aef06cd358cfa972da1046b6a4b667ca Mon Sep 17 00:00:00 2001 From: Daniel Rosen Date: Wed, 9 Jul 2025 11:29:30 -0600 Subject: [PATCH 2/2] Cleanup CONTRIBUTING.md --- CONTRIBUTING.md | 42 +++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0ca0a554ef..61aef9f52a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,7 @@ -The [Earth System Modeling Framework](https://earthsystemmodeling.org/) (ESMF) is high-performance, flexible software infrastructure for building and coupling weather, climate, and related Earth science applications. +The [Earth System Modeling Framework](https://earthsystemmodeling.org/) (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. [fork]: https://github.com/esmf-org/esmf/fork [pr]: https://github.com/esmf-org/esmf/compare @@ -17,35 +20,44 @@ The [Earth System Modeling Framework](https://earthsystemmodeling.org/) (ESMF) i 1. [Fork][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 +3. Make and [test](#testing) your changes +4. Update [documentation](#documentation) 5. Push to your fork -6. Execute `ESMF CI` and `ESMF Docs` from your fork on your branch using [Actions][actions] -7. Compare across forks and [Submit a pull request][pr] +6. Execute `ESMF CI` and `ESMF Docs` from your fork on your branch using [actions][actions] +7. Compare across forks and [submit a pull request][pr] ## Testing -Pull requests must pass the [ESMF CI][actions] action before they are accepted into the `develop` branch. The [ESMF CI][actions] 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][actions] action, changes should pass `make all_tests` on a local machine or HPC. +Pull requests must pass the [ESMF CI][actions] action before they are accepted +into the `develop` branch. The [ESMF CI][actions] 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][actions] action, changes should pass `make all_tests` on a local +machine or HPC. ## Documentation -ESMF uses LaTeX and LaTeX extensions to build documentation. Documentation can be built using the [ESMF Docs][actions] action. 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 uses LaTeX and LaTeX extensions to build inline documentation. +Documentation can be built using the [ESMF Docs][actions] 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` -## Coding conventions - -* Indent using two spaces - ## Contact Us -[ESMF Discussions](https://github.com/orgs/esmf-org/discussions) is a GitHub Discussions forum for publicly discussing ESMF concerns and requests. For more information please see the [ESMF Discussions How-To Guide](https://github.com/orgs/esmf-org/discussions/246). -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. +[ESMF Discussions](https://github.com/orgs/esmf-org/discussions) is a GitHub +Discussions forum for publicly discussing ESMF concerns and requests. For more +information please see the +[ESMF Discussions How-To Guide](https://github.com/orgs/esmf-org/discussions/246). + +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,