Merge pull request #304 from xylar/omega/doc/document-omega-pr-suite

Better document testing requirements for Omega PRs

This merge adds a "Code Testing" page to the documentation that describes running the omega_pr test suite for
each Omega PR.

It also updates the PR checklist to better describe testing. The updated version provides better links to the documentation
and a more thorough list of testing requirements.

It includes many fixes to typos in the Quick Start.

Author: xylar

.github/pull_request_template.md

@@ -8,19 +8,27 @@ Below are a few things we ask you or your reviewers to kindly check.
 -->
 Checklist
 * [ ] Documentation:
-  * [ ] Design document has been generated and added to the docs
-  * [ ] User's Guide has been updated
-  * [ ] Developer's Guide has been updated
-  * [ ] Documentation has been [built locally](https://e3sm-project.github.io/Omega/omega/develop/devGuide/BuildDocs.html) and changes look as expected
+  * [ ] Design document has been generated and [added to the docs](https://github.com/E3SM-Project/Omega/tree/develop/components/omega/doc/design)
+  * [ ] [User's Guide](https://github.com/E3SM-Project/Omega/tree/develop/components/omega/doc/userGuide) has been updated
+  * [ ] [Developer's Guide](https://github.com/E3SM-Project/Omega/tree/develop/components/omega/doc/devGuide) has been updated
+  * [ ] Documentation has been [built locally](https://docs.e3sm.org/Omega/Omega/devGuide/BuildDocs.html) and changes look as expected
+* [ ] Linting
+  * [ ] [Pre-commit](https://docs.e3sm.org/Omega/Omega/devGuide/Linting.html) run locally
 * [ ] Building
   * [ ] CMake build does not produce any new warnings from changes in this PR
 * [ ] Testing
-  * [ ] A comment in the PR documents testing used to verify the changes including any tests that are added/modified/impacted.
-  * [ ] CTest unit tests for new features have been added per the approved design.
-  * [ ] Polaris tests for new features have been added per the approved design (and included in a test suite)
-  * [ ] Unit tests have passed. Please provide a relevant CDash build entry for verification.
-  * [ ] Polaris test suite has passed
-  * [ ] Performance related PRs: Please include a relevant PACE experiment link documenting performance before and after.
+  * [ ] Add a comment to the PR titled `Testing` with the following:
+    * [ ] Which machines [CTest unit tests](https://docs.e3sm.org/Omega/Omega/devGuide/QuickStart.html#running-ctests)
+          have been run on and indicate that are all passing.
+    * [ ] The [Polaris omega_pr test suite](https://docs.e3sm.org/Omega/Omega/devGuide/Testing.html)
+       has passed, using the Polaris `e3sm_submodules/Omega` baseline
+    * [ ] Document machine(s), compiler(s), and the build path(s) used for `-p` for both the baseline (Polaris `e3sm_submodules/Omega`) and the PR build
+    * [ ] Indicate "All tests passed" or document failing tests
+    * [ ] Document testing used to verify the changes including any tests that are added/modified/impacted.
+    * [ ] Performance related PRs: Please include a relevant PACE experiment link documenting performance before and after.
+  * [ ] New tests:
+    * [ ] CTest unit tests for new features have been added per the approved design.
+    * [ ] Polaris tests for new features have been added per the approved design (and included in a test suite)
 * [ ] Stealth Features
   * [ ] If any stealth features are included in the PR, please confirm that they have been documented.
 

components/omega/doc/devGuide/QuickStart.md

@@ -12,10 +12,10 @@ branches.  To do this, go to the page for the
 click on the `fork` button near the upper right corner.  Set "owner" to your
 GitHub username (this should be the default) and click "Create fork".
 
-There is no need to have a separate for for Omega, since the Omega repository
-is also a fork of E3SM.  Your E3SM fork will server for both E3SM and Omega
+There is no need to have a separate fork for Omega, since the Omega repository
+is also a fork of E3SM.  Your E3SM fork will serve for both E3SM and Omega
 development.  In fact, GitHub will not let you make an Omega fork if you
-already have an E3SM fork (or visa versa).
+already have an E3SM fork (or vice versa).
 
 ### Check out the code
 
@@ -52,7 +52,7 @@ If you do not have conda set up in your own space yet, follow
 
 
 Activate the `base` conda environment.  Go to the base of the Omega branch you
-plan to develop and create conda environment for
+plan to develop and create a conda environment for
 linting your code and building the documentation:
 ```sh
 cd components/omega/
@@ -74,13 +74,19 @@ that `pre-commit` and the associated linting utilities are available and that
 they check your code as it is committed (rather than requiring fix-up commits
 later on).
 
+(omega-dev-quick-start-build-test)=
+
 ## Building and testing Omega
 
+(omega-dev-quick-start-ctest-util)=
+
 ### Polaris CTest Utility
 
 If you are using Polaris, you may wish to use its
 [Omega CTest utility](https://github.com/E3SM-Project/polaris/tree/main/utils/omega/ctest)
-to buid and test Omega. The utility automates many of the steps below.
+to build and test Omega. The utility automates many of the steps below.
+
+(omega-dev-quick-start-build)=
 
 ### Building Omega
 
@@ -96,7 +102,7 @@ git submodule update --init --recursive \
     cime
 ```
 
-Since some systems require tests to be run on in a scratch space, it is a good
+Since some systems require tests to be run in a scratch space, it is a good
 idea to build the code somewhere in your scratch space.  We will simply refer
 to the build directory as `$BUILD_DIR` and leave it up to you to decide where
 it is best to put it.  If you have previously built in `$BUILD_DIR`, you
@@ -109,8 +115,8 @@ cd $BUILD_DIR
 
 Set `$PARMETIS_ROOT` to the appropriate location for Metis and Parmetis
 libraries built for your machine and compiler (see
-{ref}`omega-dev-parmetis-libs` below for some shared locations on some
-supported machines):
+{ref}`omega-dev-parmetis-libs` below for shared locations on supported
+machines):
 ```sh
 export PARMETIS_ROOT=<parmetis_root>
 ```
@@ -204,8 +210,8 @@ Total Test time (real) =   8.91 sec
 
 If Omega CTests are failing or simulations are crashing, setting
 `OMEGA_BUILD_TYPE` to `Debug` can be helpful for debugging purposes. If you
-need to identify which test has failed, it may be useful to examine the CMake
-ctest log file located at `$BUILD_DIR/Testing/Temporary/LastTest.log`.
+need to identify which test has failed, it may be useful to examine the CTest
+log file located at `$BUILD_DIR/Testing/Temporary/LastTest.log`.
 
 (omega-dev-parmetis-libs)=
 
@@ -264,16 +270,16 @@ used to but the hope is that it leads to a coherent code style in Omega.
 You may wish to consider using an integrated development environment (IDE) to
 develop your code.  A convenient option for developing on HPC is
 [Visual Studio Code (VS Code)](https://code.visualstudio.com/).  It has plugins
-for [c++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools),
+for [C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools),
 [CMake](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools),
 [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python),
 and so on.  If configured correctly, it should help to enforce the
 [code formatting style](https://code.visualstudio.com/docs/cpp/cpp-ide#_code-formatting)
 by recognizing Omega's `.clang-format` file.
 
-A convenient feature is the ability to connect to edit code directly on HPC
+A convenient feature is the ability to connect and edit code directly on HPC
 systems from your laptop or desktop
-[using a n SSH connection](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh).
+[using an SSH connection](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh).
 
 VS Code also provides a convenient way to preview the Markdown files used in
 the Omega documentation as you are writing them.