diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index d1e3c52fc4..ee361a4407 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -7,26 +7,38 @@ assignees: '' --- -# Description + -Provide a clear and concise description of the bug and what behavior you are expecting. +Your bug may already be reported! +Please search on the [Issue tracker](https://github.com/ufs-community/ufs-srweather-app/issues) before creating a new issue. +If an issue already exists, please use that issue to add any additional information. -## Steps to Reproduce +## Expected behavior + -Please provide detailed steps for reproducing the issue. +## Current behavior + -1. step 1 -2. step 2 -3. see the bug... +## Machines affected + + -## Additional Context +## Steps To Reproduce + -Please provide any relevant information about your setup. This is important in case the issue is not reproducible except for under certain conditions. +## Detailed Description of Fix (optional) + -* Machine -* Compiler -* Reference other issues or PRs in other repositories that this is related to, and how they are related. +## Additional Information (optional) + -## Output +## Possible Implementation (optional) + -Please include any relevant log files, screenshots or other output here. +## Output (optional) + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index c5f7619d81..05913d4ab1 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -7,14 +7,35 @@ assignees: '' --- + + +Your issue may already be reported! +Please search on the [Issue tracker](https://github.com/ufs-community/ufs-srweather-app/issues) before creating a new issue. If an issue already exists, please use that issue to add any additional information. + ## Description -Provide a clear and concise description of the problem to be solved. + + + ## Solution -Add a clear and concise description of the proposed solution. + + +## Requirements** + + +## Acceptance Criteria (Definition of Done) + -## Alternatives (optional) -If applicable, add a description of any alternative solutions or features you've considered. +## Dependencies (optional) + + -## Related to (optional) -Directly reference any issues or PRs in this or other repositories that this is related to, and describe how they are related. +## Alternative Solutions (optional) + diff --git a/.github/ISSUE_TEMPLATE/textonly_request.md b/.github/ISSUE_TEMPLATE/textonly_request.md index e2be6bb5fe..2764d6a6d6 100644 --- a/.github/ISSUE_TEMPLATE/textonly_request.md +++ b/.github/ISSUE_TEMPLATE/textonly_request.md @@ -8,13 +8,13 @@ assignees: '' --- ## Description -Provide a clear and concise description of the problem to be solved. + ## Solution -Add a clear and concise description of the proposed solution. + ## Alternatives (optional) -If applicable, add a description of any alternative solutions or features you've considered. + ## Related to (optional) -Directly reference any issues or PRs in this or other repositories that this is related to, and describe how they are related. + diff --git a/.github/PULL_REQUEST_TEMPLATE b/.github/PULL_REQUEST_TEMPLATE index bad27f0f7e..d3c5a1b3e4 100644 --- a/.github/PULL_REQUEST_TEMPLATE +++ b/.github/PULL_REQUEST_TEMPLATE @@ -1,33 +1,91 @@ + +- Update develop to head at ufs-community + - Use this template to give a detailed message describing the change you want to make to the code. -- You may delete any sections labeled "optional". +- You may delete any sections labeled "optional" and any instructions within . + +- If you are unclear on what should be written here, see https://github.com/wrf-model/WRF/wiki/Making-a-good-pull-request-message for some guidance and review the Code Contributor's Guide at https://github.com/ufs-community/ufs-srweather-app/wiki/Code-Manager's-Guide. -- If you are unclear on what should be written here, see https://github.com/wrf-model/WRF/wiki/Making-a-good-pull-request-message for some guidance. +- Code reviewers will assess the PR based on the criteria laid out in the Code Reviewer's Guide (https://github.com/ufs-community/ufs-srweather-app/wiki/Code-Manager's-Guide). -- The title of this pull request should be a brief summary (ideally less than 100 characters) of the changes included in this PR. Please also include the branch to which this PR is being issued. +- The title of this pull request should be a brief summary (ideally less than 100 characters) of the changes included in this PR. Please also include the branch to which this PR is being issued (e.g., "[develop]: Updated UFS_UTILS hash"). - Use the "Preview" tab to see what your PR will look like when you hit "Create pull request" + # --- Delete this line and those above before hitting "Create pull request" --- ## DESCRIPTION OF CHANGES: -One or more paragraphs describing the problem, solution, and required changes. + + +### Type of change + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] This change requires a documentation update ## TESTS CONDUCTED: -Explicitly state what tests were run on these changes, or if any are still pending (for README or other text-only changes, just put "None required". Make note of the compilers used, the platform/machine, and other relevant details as necessary. For more complicated changes, or those resulting in scientific changes, please be explicit! + + + +- [ ] hera.intel +- [ ] orion.intel +- [ ] cheyenne.intel +- [ ] cheyenne.gnu +- [ ] gaea.intel +- [ ] jet.intel +- [ ] wcoss2.intel +- [ ] NOAA Cloud (indicate which platform) +- [ ] Jenkins +- [ ] fundamental test suite +- [ ] comprehensive tests (specify *which* if a subset was used) ## DEPENDENCIES: -Add any links to external PRs (e.g. regional_workflow and/or UFS PRs). For example: + ## DOCUMENTATION: -If this PR is contributing new capabilities that need to be documented, please also include updates to the RST files (docs/UsersGuide/source) as supporting material. + + +## ISSUE: + + +## CHECKLIST + +- [ ] My code follows the style guidelines in the Contributor's Guide +- [ ] I have performed a self-review of my own code using the Code Reviewer's Guide +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] My changes need updates to the documentation. I have made corresponding changes to the documentation +- [ ] My changes do not require updates to the documentation (explain). +- [ ] My changes generate no new warnings +- [ ] New and existing tests pass with my changes +- [ ] Any dependent changes have been merged and published -## ISSUE (optional): -If this PR is resolving or referencing one or more issues, in this repository or elewhere, list them here. For example, "Fixes issue mentioned in #123" or "Related to bug in https://github.com/ufs-community/other_repository/pull/63" +## LABELS (optional): + +A Code Manager needs to add the following labels to this PR: +- [ ] Work In Progress +- [ ] bug +- [ ] enhancement +- [ ] documentation +- [ ] release +- [ ] high priority +- [ ] run_ci +- [ ] run_we2e_fundamental_tests +- [ ] run_we2e_comprehensive_tests +- [ ] Needs Cheyenne test +- [ ] Needs Jet test +- [ ] Needs Hera test +- [ ] Needs Orion test +- [ ] help wanted ## CONTRIBUTORS (optional): -If others have contributed to this work aside from the PR author, list them here + + + diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index caccca06dc..fbe1cf910d 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -35,7 +35,10 @@ The prognostic atmospheric model in the UFS SRW Application is the Finite-Volume Supported model resolutions in this release include 3-, 13-, and 25-km predefined contiguous U.S. (:term:`CONUS`) domains, each with 127 vertical levels. Preliminary tools for users to define their own domain are also available in the release with full, formal support of these tools to be provided in future releases. The Extended Schmidt Gnomonic (ESG) grid is used with the FV3-LAM, which features relatively uniform grid cells across the entirety of the domain. Additional information about the FV3 dynamical core can be found in the `scientific documentation `__, the `technical documentation `__, and on the `NOAA Geophysical Fluid Dynamics Laboratory website `__. -Interoperable atmospheric physics, along with various land surface model options, are supported through the Common Community Physics Package (CCPP), described `here `__. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There will be four physics suites supported for the SRW App v2.0.0 release. The first is the FV3_RRFS_v1beta physics suite, which is being tested for use in the future operational implementation of the Rapid Refresh Forecast System (RRFS) planned for 2023-2024, and the second is an updated version of the physics suite used in the operational Global Forecast System (GFS) v16. Additionally, FV3_WoFS and FV3_HRRR will be supported. A scientific description of the CCPP parameterizations and suites can be found in the `CCPP Scientific Documentation `__, and CCPP technical aspects are described in the `CCPP Technical Documentation `__. The model namelist has many settings beyond the physics options that can optimize various aspects of the model for use with each of the supported suites. Additional information on Stochastic Physics options is available `here `__. +Interoperable atmospheric physics, along with various land surface model options, are supported through the Common Community Physics Package (CCPP), described `here `__. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. There will be four physics suites supported for the SRW App v2.0.0 release. The first is the FV3_RRFS_v1beta physics suite, which is being tested for use in the future operational implementation of the Rapid Refresh Forecast System (RRFS) planned for 2023-2024, and the second is an updated version of the physics suite used in the operational Global Forecast System (GFS) v16. Additionally, FV3_WoFS_v0 and FV3_HRRR will be supported. A scientific description of the CCPP parameterizations and suites can be found in the `CCPP Scientific Documentation `__, and CCPP technical aspects are described in the `CCPP Technical Documentation `__. The model namelist has many settings beyond the physics options that can optimize various aspects of the model for use with each of the supported suites. Additional information on Stochastic Physics options is available `here `__. + +.. note:: + SPP is currently only available for specific physics schemes used in the RAP/HRRR physics suite. Users need to be aware of which physics suite definition file (:term:`SDF`) is chosen when turning this option on. Among the supported physics suites, the full set of parameterizations can only be used with the ``FV3_HRRR`` option for ``CCPP_PHYS_SUITE``. The SRW App supports the use of both :term:`GRIB2` and :term:`NEMSIO` input data. The UFS Weather Model ingests initial and lateral boundary condition files produced by :term:`chgres_cube` and outputs files in netCDF format on a specific projection (e.g., Lambert Conformal) in the horizontal direction and model levels in the vertical direction. diff --git a/docs/UsersGuide/source/ContributorsGuide.rst b/docs/UsersGuide/source/ContributorsGuide.rst index 3e3437c0ff..e7b99f00f3 100644 --- a/docs/UsersGuide/source/ContributorsGuide.rst +++ b/docs/UsersGuide/source/ContributorsGuide.rst @@ -13,11 +13,11 @@ Background Authoritative branch ----------------------- -The main development branch for the ``ufs-srweather-app`` repository is ``develop``. The HEAD of ``develop`` reflects the latest development changes. It points to regularly updated hashes for individual sub-components, including the ``regional_workflow``. Pull requests (PRs) will be merged to ``develop``. +The ``ufs-srweather-app`` and ``regional_workflow`` repositories each maintain a main branch for development called ``develop``. The HEAD of ``develop`` reflects the latest development changes. It points to regularly updated hashes for individual sub-components. Pull requests (PRs) will be merged to ``develop``. The ``develop`` branch is protected by the code management team: #. Pull requests for this branch require approval by at least two code reviewers. - #. A code manager should perform the review and the merge, but other contributors are welcome to provide comments/suggestions. + #. A code manager should perform at least one of the reviews and the merge, but other contributors are welcome to provide comments/suggestions. Code Management Team @@ -27,67 +27,66 @@ Scientists from across multiple labs and organizations have volunteered to revie .. table:: - +------------------+------------------------------------------------+ - | **Organization** | **Reviewers** | - +==================+================================================+ - | EMC | Chan-Hoo Jeon (@chan-hoo) | - | | | - | | Ben Blake (@BenjaminBlake-NOAA) | - | | | - | | Ratko Vasic (@RatkoVasic-NOAA) | - +------------------+------------------------------------------------+ - | EPIC | Mark Potts (@mark-a-potts) | - | | | - | | Jong Kim (@jkbk2004) | - | | | - | | Natalie Perlin (@natalie-perlin) | - | | | - | | Gillian Petro (@gspetro-NOAA) | - | | | - | | Edward Snyder (@EdwardSnyder-NOAA) | - +------------------+------------------------------------------------+ - | GLERL/UM | David Wright (@dmwright526) | - +------------------+------------------------------------------------+ - | GSL | Jeff Beck (@JeffBeck-NOAA) | - | | | - | | Gerard Ketefian (@gsketefian) | - | | | - | | Linlin Pan (@panll) | - | | | - | | Christina Holt (@christinaholtNOAA) | - | | | - | | Christopher Harrop (@christopherwharrop-noaa) | - | | | - | | Daniel Abdi (@danielabdi-noaa) | - +------------------+------------------------------------------------+ - | NCAR | Mike Kavulich (@mkavulich) | - | | | - | | Will Mayfield (@willmayfield) | - +------------------+------------------------------------------------+ - | NSSL | Yunheng Wang (@ywangwof) | - +------------------+------------------------------------------------+ - + +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ + | **Organization** | **Reviewers** | **Areas of Expertise** | + +==================+================================================+===================================================================================+ + | EMC | Chan-Hoo Jeon (@chan-hoo) | Workflow, NCO requirements, and operational platform testing | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Ben Blake (@BenjaminBlake-NOAA) | Output visualization, Rocoto | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Ratko Vasic (@RatkoVasic-NOAA) | Workflow, NCO requirements, and operational platform testing | + +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ + | EPIC | Mark Potts (@mark-a-potts) | HPC systems | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Jong Kim (@jkbk2004) | UFS Weather Model configuration, forecast sensitivity analysis, data assimilation | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Natalie Perlin (@natalie-perlin) | Generic Linux/Mac installations, hpc-stack/spack-stack | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Gillian Petro (@gspetro-NOAA) | Documentation | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Edward Snyder (@EdwardSnyder-NOAA) | WE2E testing, input data | + +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ + | GLERL | David Wright (@dmwright526) | FVCOM integration, output visualization, preprocessing tasks | + +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ + | GSL | Jeff Beck (@JeffBeck-NOAA) | SRW App configuration/workflow, code management, meteorological evaluation | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Gerard Ketefian (@gsketefian) | ``regional_workflow`` scripts, jinja templates, and verification tasks | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Linlin Pan (@panll) | Workflow, CCPP/physics, verification | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Christina Holt (@christinaholtNOAA) | Workflow, conda environment support, testing, and code management | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Christopher Harrop (@christopherwharrop-noaa) | Rocoto, code management, and testing | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Daniel Abdi (@danielabdi-noaa) | Workflow generation, testing RRFS on the cloud, environment modules | + +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ + | NCAR | Mike Kavulich (@mkavulich) | CCPP/physics | + | +------------------------------------------------+-----------------------------------------------------------------------------------+ + | | Will Mayfield (@willmayfield) | Verification/METplus tasks, regional_workflow (esp. on Cheyenne) | + +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ + | NSSL | Yunheng Wang (@ywangwof) | HPC systems, code management and regional workflow especially on Stampede, Jet | + | | | and NSSL computers | + +------------------+------------------------------------------------+-----------------------------------------------------------------------------------+ .. _ContribProcess: Contribution Process ======================== -The steps below should be followed in order to make changes to the ``develop`` branch of the ``ufs-srweather-app`` repository. Communication with code managers and the code management team throughout the process is encouraged. +The steps below should be followed in order to make changes to the ``develop`` branch of the ``ufs-srweather-app`` or ``regional_workflow`` repositories. Communication with code managers and the code management team throughout the process is encouraged. #. **Issue** - Open an issue to document changes. Click `here `__ to open a new ``ufs-srweather-app`` issue or see :numref:`Step %s ` for detailed instructions. #. **GitFlow** - Follow `GitFlow `__ procedures for development. #. **Fork the repository** - Read more `here `__ about forking in GitHub. - #. **Create a branch** - Create a branch in your fork of the authoritative repository. Follow `GitFlow `__ conventions when creating the branch. Branches should be named as follows, where [name] is a one-word description of the branch: + #. **Create a branch** - Create a branch in your fork of the authoritative repository. Follow `GitFlow `__ conventions when creating the branch. All development should take place on a branch, *not* on ``develop``. Branches should be named as follows, where [name] is a one-word description of the branch: * **bugfix/[name]:** Fixes a demonstrably incorrect portion of code - * **feature/[name]:** Adds a new feature to the code - * **enhancement/[name]:** Improves an existing portion of the code - * **textonly/[name]:** Changes elements of the repository that do not impact program output or log files (e.g., changes to README, documentation, comments, changing quoted Registry elements, white space alignment). Any change which does not impact the compiled code in any way should fall under this category. + * **feature/[name]:** Adds a new feature to the code or improves an existing portion of the code + * **text/[name]:** Changes elements of the repository that do not impact program output or log files (e.g., changes to README, documentation, comments, changing quoted Registry elements, white space alignment). Any change that does not impact the compiled code in any way should fall under this category. - #. **Development** - Perform and test changes in the branch. Document work in the issue and mention the issue number in commit messages to link your work to the issue (e.g., ``commit -m "Issue #23 - "``). Test code modifications on as many platforms as possible, and request help with further testing from the code management team when unable to test on all platforms. Document changes to the workflow and capabilities (either in the ``.rst`` files or separately) so that the SRW App documentation stays up-to-date. - #. **Pull request** - When ready to merge changes back to the ``develop`` branch, the code developer should initiate a pull request (PR) of the feature branch into the ``develop`` branch. Read `here `__ about pull requests in GitHub. When a PR is initiated, the :ref:`PR Template