Sync with base repository

.github/CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to WRF-Hydro
+# Contributing to WRF-Hydro®
 All bug reports, bug fixes, code, and documentation contributions are welcome and encouraged.
 However, guidelines need to be established and followed to ensure that community contributions can
 be effectively incorporated.
@@ -24,7 +24,7 @@ https://help.github.com/articles/about-issues/.
 
 ### Bug reports
 Please use the supplied issue template when submitting bug reports. This will help ensure that your
-bug is described in sufficient detail. Additionally, you can read more on how to construct an
+bug is described in sufficient detail. You can read more on how to construct an
 appropriate bug report here: https://stackoverflow.com/help/mcve
 
 ### Feature requests
@@ -41,8 +41,7 @@ documentation.
 All code development contributions will be made via [forks](https://help.github.com/articles/about-forks/)
 and [pull requests](https://help.github.com/articles/about-pull-requests/). If you are
 unfamiliar with GitHub, forks, or pull requests, see [collaborating with issues and pull
-requests](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/) for a
-thorough guide to collaborating on GitHub.
+requests](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/) for guidance.
 
 ### WRF-Hydro Fortran code style standards
 Please see our Fortran [code style guidelines](CODESTYLE.md)
@@ -56,7 +55,7 @@ Please see our Fortran [code style guidelines](CODESTYLE.md)
   contributor to resolve any merge conflicts **prior** to submitting a pull request.
 * All contributions must pass relevant automated testing procedures. These tests are executed
   automatically when you submit your pull request.
-* Be respectful when giving and receiving feedback on contributions or issues.
+* Be respectful when giving and receiving feedback on contributions or issues (see our community [code of conduct](../CODE_OF_CONDUCT.md).
 
 ### Pull requests
 
@@ -82,11 +81,11 @@ which changes the answer must be isolated as much as possible into its own pull
 ### Types of code contributions
 #### Bug fixes
 All bug fixes must address a specific [GitHub
-issue](https://github.com/NCAR/wrf_hydro_nwm_public/issues). Only issues labeled with "Community
-dev" are open to community contributions. The majority of issues will be open to community
-contributions, but some cases may require more careful handling. Issues without the "Community dev"
-label are either still being investigated, are of broad scope, or involve changes to code that is
-actively being developed internally.
+issue](https://github.com/NCAR/wrf_hydro_nwm_public/issues). Only issues labeled with ["community
+dev"](https://github.com/NCAR/wrf_hydro_nwm_public/labels/community%20dev) are open to community 
+contributions. The majority of issues will be open to community contributions, but some cases may 
+require more careful handling. Issues without the "community dev" label are either still being 
+investigated, are of broad scope, or involve changes to code that is actively being developed internally.
 
 All code changes to address issues must be submitted using a pull request, and the corresponding
 issue number must be referenced in the pull request. For more information on referencing issues,
@@ -96,7 +95,7 @@ see [issues and keywords](https://help.github.com/articles/closing-issues-using-
 Code contributions for minor model enhancements or new features follow a similar pattern to bug
 fixes. The proposed feature must be submitted as a GitHub issue and all discussions regarding the
 new feature should reside in the issue thread. Additionally, work should not begin on the new
-feature until the issue has been tagged with "Community dev".
+feature until the issue has been tagged with "community dev".
 
 Depending on the scope of the new feature, a WRF-Hydro core contributor may suggest you create a
 [branch](https://help.github.com/articles/about-branches/) to hold all development for the new
@@ -107,3 +106,49 @@ Larger-scale research development, e.g. model coupling, must be coordinated with
 member prior to beginning work. This type of development may impact other community projects and
 requires more careful governance to help steer the direction of model development and maximize
 harmony among the various NCAR, NOAA, and WRF-Hydro community research efforts.
+
+### Checklist for new feature contributions
+#### You should have the following to submit a new feature contribution to the WRF-Hydro code base:
+1. A WRF-Hydro team point of contact (POC). Early in your development process, it is always a good idea 
+to reach out to the WRF-Hydro team and find a good POC for your new feature. This person will help 
+keep you informed of new developments as they may relate to your feature, advise you on which branches 
+to keep current with (if other than master), and provide pointers on requirements.
+2. New feature code integrated in with the latest WRF-Hydro master branch (or other as advised by your 
+WRF-Hydro POC). This merged code should exist in your own fork, but can be in your own master branch or 
+a separate feature branch.
+   * *TIP #1*: It is always a good strategy to pull the latest WRF-Hydro master code into your branch 
+fairly often throughout your development cycle. Leaving months of code changes to merge at the end of 
+your development cycle can result in lots of merge conflicts, time-consuming manual edits, and higher 
+potential for making errors.
+   * *TIP #2*: New code should follow the 
+[WRF-Hydro code contribution guidelines](https://github.com/NCAR/wrf_hydro_nwm_public/blob/master/.github/CONTRIBUTING.md).
+3. Documentation for your new feature. This should include (1) a simple summary in the release notes 
+(added to [NEWS.md](https://github.com/NCAR/wrf_hydro_nwm_public/blob/master/NEWS.md)), and (2) a 
+detailed description of the new feature suitable to be included within the 
+[WRF-Hydro Technical Description](https://ral.ucar.edu/sites/default/files/public/projects/wrf_hydro/technical-description-user-guide/wrf-hydro-v5.1.1-technical-description.pdf), 
+included as a new markdown document in the 
+[Doc](https://github.com/NCAR/wrf_hydro_nwm_public/tree/master/trunk/NDHMS/Doc) 
+folder.
+4. An updated 
+[standalone test case](https://ral.ucar.edu/projects/wrf_hydro/testcases) demonstrating how 
+your new feature works, based on one of the existing WRF-Hydro test cases (e.g., Croton). If you cannot 
+adapt an existing test case and need to create something new, please consult with your POC. The test 
+case should include:
+   * Domain and parameter files
+   * Namelists
+   * Example forcings if needed (idealized forcing use is OK)
+   * Test case documentation
+5. Testing - you must clearly demonstrate that your new feature:
+   * Does no harm to the existing code (e.g., produces identical solutions EXCEPT when the new feature is 
+activated by a namelist or parameter setting).
+   * Fixes a documented issue (reference existing issue in the 
+[WRF-Hydro GitHub issue tracking](https://github.com/NCAR/wrf_hydro_nwm_public/issues) - this could also be a feature request).
+   * If model performance is improved, for example through more efficient IO, memory utilization, or other 
+software-specific improvements, it must be demonstrable and measurable.
+   * *TIP*: All pull requests go through automated CI testing, but for a new feature it is important to do 
+thorough testing ahead of time so you have a good sense of the model impacts and can explain/justify them. 
+Do not wait until automated CI testing to test your new feature.
+6. A pull request from a branch on your fork to the WRF-Hydro master branch (or other as advised by your 
+WRF-Hydro POC). Make sure to also follow the specific 
+[WRF-Hydro pull request guidelines](https://github.com/NCAR/wrf_hydro_nwm_public/blob/master/.github/PULL_REQUEST_TEMPLATE.md).
+

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+If you haven't already, please review our [contributing guidelines](CONTRIBUTING.md) before opening your pull request.
+
+Use this template to give a detailed message describing the change you want to make to the code.
+
+The title of this pull request should be a brief "purpose" for this change.
+
+--- Delete this line and those above before hitting "Create pull request" ---
+
+TYPE: choose one of [bug fix, enhancement, new feature, feature removed, no impact, text only]
+
+KEYWORDS: approximately 3 to 6 words (more is always better) related to your commit, separated by commas
+
+SOURCE: Developer's name and affiliation 
+
+DESCRIPTION OF CHANGES: One or more paragraphs describing problem, solution, and required changes.
+
+ISSUE: The GitHub Issue that this PR addresses. For issue number 123, it would be:
+```
+Fixes #123
+```
+
+TESTS CONDUCTED: Explicitly state if regression, integration, or unit tests were run before submitting (do not include the CI tests automatically run by GitHub)
+
+NOTES: Optional, as appropriate. Delete if not used. Included only once for new features requiring several merge cycles. Changes to default behavior are also note worthy.
+
+
+### Checklist
+Merging the PR depends on following checklist being completed. Add `X` between each of the square 
+brackets if they are completed in the PR itself. If a bullet is not relevant to you, please comment 
+on why below the bullet.
+
+ - [ ] Closes issue #xxxx (An issue must exist or be created to be closed. The issue describes and documents the problem and general solution, the PR describes the technical details of the solution.) 
+ - [ ] Tests added (unit tests and/or regression/integration tests)
+ - [ ] Backwards compatible
+ - [ ] Requires new files? If so, how to generate them.
+ - [ ] Documentation included
+ - [ ] Short description in the Development section of `NEWS.md`

.github/workflows/test-pr.yml

@@ -0,0 +1,74 @@
+name: WRF-Hydro CI
+
+on:
+  push:
+    branches: [ master, v5.2.x ]
+  pull_request:
+    branches: [ master, v5.2.x ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: "PR to test"
+        required: true
+
+jobs:
+  Model_Testing:
+    strategy:
+      fail-fast: false
+      matrix:
+        configuration: [nwm_ana, nwm_long_range, gridded, reach]
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout candidate (pull request / push)
+        if: ${{ github.event_name == 'pull_request' || github.event_name == 'push' }}
+        uses: actions/checkout@v2
+        with:
+          path: candidate
+
+      - name: Checkout candidate (manual)
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        env: 
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+        run: gh repo clone ${{ github.repository }} candidate && cd candidate && gh pr checkout -R ${{ github.repository }} ${{ github.event.inputs.pr }}
+
+      - name: Checkout reference (pull request)
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/checkout@v2
+        with:
+          ref: ${{ github.event.pull_request.base.ref }}
+          path: reference
+
+      - name: Checkout reference (push)
+        if: ${{ github.event_name == 'push' }}
+        uses: actions/checkout@v2
+        with:
+          ref: ${{ github.event.before }}
+          path: reference
+
+      - name: Checkout reference (manual)
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        env: 
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+        run: gh repo clone ${{ github.repository }} reference && cd reference && git checkout origin/$(gh pr view ${{ github.event.inputs.pr }} --json baseRefName --jq '.baseRefName')
+
+      - name: Run testing container
+        run: |
+          docker run -e TRAVIS=1 -t --name test_container \
+           -v $GITHUB_WORKSPACE/candidate:/home/docker/candidate \
+           -v $GITHUB_WORKSPACE/reference:/home/docker/reference \
+           wrfhydro/dev:modeltesting --config ${{ matrix.configuration }} --domain_tag dev
+
+      - name: Copy test results from container
+        if: ${{ always() }}
+        run: docker cp test_container:/home/docker/test_out $GITHUB_WORKSPACE/test_report
+
+      - name: Archive test results to GitHub
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v2
+        with:
+          name: test-reports
+          path: ${{ github.workspace }}/test_report/**.html
+

.gitignore

@@ -1,16 +1,16 @@
 *.o
-*.f
-*.f90
-*.F90
 *.mod
+*.lst
 *~
 Makefile.comm
 trunk/NDHMS/lib/*
 trunk/NDHMS/macros
 trunk/NDHMS/HRLDAS/user_build_options
 *exe
 /.project
-trunk/NDHMS/Run/*.exe
+trunk/NDHMS/Run
+trunk/NDHMS/Run/
+trunk/NDHMS/setEnvar.sh
 trunk/NDHMS/Makefile.comm
 trunk/NDHMS/Land_models/NoahMP/user_build_options
 trunk/NDHMS/Land_models/Noah/user_build_options
@@ -23,3 +23,5 @@ README.md
 *pytest_cache*
 *.log
 compile_options.sh
+.DS_Store
+