diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 2a9af342..549b3128 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,16 +1,8 @@ -### All Submissions: +### Description of changes: -* [ ] Have you followed the guidelines in our [Contributor's Guide](https://github.com/NCAR/CUPiD/wiki/Contributor's-Guide) (including the `pre-commit` check)? +* [ ] Have you followed the guidelines in our [Contributor's Guide](https://ncar.github.io/CUPiD/ContributorGuide.html)? * [ ] Have you checked to ensure there aren't other open [Pull Requests](../../../pulls) for the same update/change? - - - -### New Feature Submissions: - -1. [ ] Does your submission pass tests? -2. [ ] Have you lint your code locally prior to submission? - -### Changes to Core Features: - +* [ ] Have you made sure that the [`pre-commit` checks passed (#8 in Adding Notebooks Guide)](https://ncar.github.io/CUPiD/addingnotebookstocollection.html)? +* [ ] Have you [hidden the code cells (#8 in Adding Notebooks Guide)](https://ncar.github.io/CUPiD/addingnotebookstocollection.html) in your notebook? * [ ] Have you added an explanation of what your changes do and why you'd like us to include them? * [ ] Have you successfully tested your changes locally? diff --git a/contributors.md b/Contributors.md similarity index 100% rename from contributors.md rename to Contributors.md diff --git a/NCAR_tips.md b/NCARtips.md similarity index 100% rename from NCAR_tips.md rename to NCARtips.md diff --git a/README.md b/README.md index 51973088..118b6b81 100644 --- a/README.md +++ b/README.md @@ -45,11 +45,10 @@ If you do not have `mamba` installed, you can still use `conda`... it will just $ pip install -e . # installs cupid ``` +1. In the `cupid-dev` environment, run `pre-commit install` to configure `git` to automatically run `pre-commit` checks when you try to commit changes from the `cupid-dev` environment; the commit will only proceed if all checks pass. Note that CUPiD uses `pre-commit` to ensure code formatting guidelines are followed, and pull requests will not be accepted if they fail the `pre-commit`-based Github Action. 1. If you plan on contributing code to CUPiD, whether developing CUPiD itself or providing notebooks for CUPiD to run, -please see the [Contributer's Guide](https://github.com/NCAR/CUPiD/wiki/Contributor's-Guide). -Note that CUPiD uses `pre-commit` to ensure code formatting guidelines are followed, -and pull requests will not be accepted if they fail the `pre-commit`-based Github Action. +please see the [Contributor's Guide](https://ncar.github.io/CUPiD/contributors_guide.html). ## Running diff --git a/docs/ContributorsGuide.md b/docs/ContributorsGuide.md new file mode 100644 index 00000000..188f6230 --- /dev/null +++ b/docs/ContributorsGuide.md @@ -0,0 +1,24 @@ +# Welcome to the CUPiD Contributor's Guide! + +Now that your repository is set up, if you would like to add a diagnostics notebook, you can follow the [guide to adding diagnostics notebooks](https://ncar.github.io/CUPiD/addingnotebookstocollection.html). + +In order to contribute code to this repository, we recommend that you get started with these steps: + +0. [Open an issue](https://github.com/NCAR/CUPiD/issues) prior to development +1. Set up git and make an account if needed. +2. Create your personal fork of the repository by going to the [CUPiD repository](https://github.com/NCAR/CUPiD) and clicking the `Fork` button. Clone your personal repository by going to your forked repository, clicking the green `Code` button, and then, in your terminal, run `git clone --recurse-submodules https://github.com//CUPiD` +3. Check out a new branch with a name that is relevant to the changes you want to make: `git checkout -b ` +4. [Install CUPiD](https://ncar.github.io/CUPiD/index.html#installing), relevant environments, and setup `pre-commit`. +5. Make your edits and add your name to our `contributors.md` file to make sure we recognize your contributions +6. Merge in recent changes from master +7. Ensure that `pre-commit` checks all pass from the `cupid-dev` environment +8. IF updating `github.io` pages, test with the steps listed below, otherwise proceed to #9: + - Create the environment necessary for building documentation with `$ conda env create -f environments/docs.yml` + - Activate the docs environment: `$ conda activate cupid-docs` + - Change into the `docs` directory: `$ cd docs` + - Build the documentation: `$ make html` + - View the documentation to make sure it rendered correctly: `$ open _build/html/index.html` +9. Submit a Pull Request +10. Await review +11. Update PR with any requested changes +12. Repository admins will merge the PR diff --git a/docs/NCARtips.rst b/docs/NCARtips.rst deleted file mode 100644 index 80201253..00000000 --- a/docs/NCARtips.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: NCAR_tips.md - :parser: myst diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index c4bee823..9ef0a4b4 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -2,6 +2,7 @@ Generally, a good fit for a diagnostic notebook is one that reads in CESM output, does some processing, and outputs plots, values, and/or new files (images, data, etc.) that are useful for evaluating the run. +0. Check out our [Contributor's Guide](https://ncar.github.io/CUPiD/contributors_guide.html) to make ensure appropriate setup of your git repository for contributions. 1. Install the `environments/cupid-analysis.yml` environment (see [installation instructions](https://ncar.github.io/CUPiD/index.html#installing)). Make sure that your notebook runs properly in this environment. If there are conflicts or missing dependencies, open an issue or talk to CUPiD developers so we can find a solution. 2. In your notebook, move all variables you might want to change (paths to data, dates to select, etc.) to a cell near the top. For example: @@ -40,4 +41,9 @@ Generally, a good fit for a diagnostic notebook is one that reads in CESM output 7. Update your parameters. Parameters that are specific to just this notebook should go under `parameter_groups` in the notebook's entry under `compute_notebooks`. Global parameters that you want passed in to every notebook in the collection should go under `global_params`. When `CUPiD` executes your notebook, all of these parameters will get put in a new cell below the cell tagged `parameters` that you added in step 3. This means they will supercede the values of the parameters that you put in the cell above---the names, notation, etc. should match to make sure your notebook is able to find the variables it needs. -8. All set! Your collection can now be run and built with `cupid-run` and `cupid-build` as usual. +8. Your collection can now be run with `cupid-run`, and then the website can be built with `cupid-build`. + +9. If you're happy with your notebook and want to add it to the CUPiD repository, there are a few formatting items that we would like contributors to follow: + * Title your notebook something descriptive. A recommended format is `___.ipynb`; for instance, this might look like `Global_PSL_NMSE_compare_obs_lens.ipynb` or `Greenland_SMB_visual_compare_obs.ipynb`. + * Add a [cell tag](https://jupyterbook.org/en/stable/content/metadata.html#jupyter-cell-tags) `hide-input` for cells which output plots, and add the tag `hide-cell` for cells that do not contain plots (this will hide both the input and output). Do this through JupyterHub when editing your notebook: click `View --> Cell Toolbar --> Tags` and add either `hide-input` or `hide-cell`. This makes it easier to glance at the plots once the webpage is built and not need to scroll through code cells. + * Set up `pre-commit` in the `cupid-dev` environment to ensure that your code is properly formatted and linted. Running `pre-commit install` will configure `git` to automatically run the `pre-commit` checks when you try to commit changes; the commit will only proceed if all the checks pass. diff --git a/docs/conf.py b/docs/conf.py index c4275235..b1585b32 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,12 +18,12 @@ print("sys.path:", sys.path) -# Copy README, NCAR_tips, and contributors into docs +# Copy README, NCAR_tips, and Contributors into docs # This block allows us to remove the header image from any md files # without affecting the original version, but still pull the source # into the docs build fresh each time. -for file in ["README.md", "NCAR_tips.md", "contributors.md"]: +for file in ["README.md", "NCARtips.md", "Contributors.md"]: os.system(f"cp ../{file} ./") # Remove any images from the first line of the file diff --git a/docs/contributors.rst b/docs/contributors.rst deleted file mode 100644 index 72746583..00000000 --- a/docs/contributors.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: contributors.md - :parser: myst diff --git a/docs/contributors_guide.rst b/docs/contributors_guide.rst new file mode 100644 index 00000000..219d1ad2 --- /dev/null +++ b/docs/contributors_guide.rst @@ -0,0 +1,2 @@ +.. include:: ContributorsGuide.md + :parser: myst diff --git a/docs/contributors_to_cupid.rst b/docs/contributors_to_cupid.rst new file mode 100644 index 00000000..387d8932 --- /dev/null +++ b/docs/contributors_to_cupid.rst @@ -0,0 +1,2 @@ +.. include:: Contributors.md + :parser: myst diff --git a/docs/index.rst b/docs/index.rst index b7156689..e636b49e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,10 +5,11 @@ CUPiD Documentation :maxdepth: 2 :hidden: + Contributor's Guide Adding Notebooks Configuration File - Tips and Tricks for NCAR Machines - Contributors + Tips and Tricks for NCAR Machines + Contributors .. include:: README.md :parser: myst diff --git a/docs/ncar_tips.rst b/docs/ncar_tips.rst new file mode 100644 index 00000000..3bd28690 --- /dev/null +++ b/docs/ncar_tips.rst @@ -0,0 +1,2 @@ +.. include:: NCARtips.md + :parser: myst diff --git a/examples/key_metrics/config.yml b/examples/key_metrics/config.yml index e559ee79..17a0b9e5 100644 --- a/examples/key_metrics/config.yml +++ b/examples/key_metrics/config.yml @@ -114,7 +114,7 @@ compute_notebooks: none: {} atm: - nmse_PSL: + Global_PSL_NMSE_compare_obs_lens: parameter_groups: none: regridded_output: False # it looks like output is already on f09 grid, didn't need to regrid time-series file @@ -122,7 +122,7 @@ compute_notebooks: validation_path: '/glade/campaign/cesm/development/cross-wg/diagnostic_framework/nmse_validation/fv0.9x1.25' glc: - LIWG_SMB_diagnostic: + Greenland_SMB_visual_compare_obs: parameter_groups: none: obs_path: '/glade/u/home/gunterl/obs_diagnostic_cesm/' @@ -191,7 +191,7 @@ book_toc: - caption: Atmosphere chapters: - - file: atm/nmse_PSL + - file: atm/Global_PSL_NMSE_compare_obs_lens # - caption: Ocean # chapters: @@ -207,7 +207,7 @@ book_toc: - caption: Land Ice chapters: - - file: glc/LIWG_SMB_diagnostic + - file: glc/Greenland_SMB_visual_compare_obs ##################################### # Keys for Jupyter Book _config.yml # diff --git a/examples/nblibrary/atm/nmse_PSL.ipynb b/examples/nblibrary/atm/Global_PSL_NMSE_compare_obs_lens.ipynb similarity index 100% rename from examples/nblibrary/atm/nmse_PSL.ipynb rename to examples/nblibrary/atm/Global_PSL_NMSE_compare_obs_lens.ipynb diff --git a/examples/nblibrary/glc/LIWG_SMB_diagnostic.ipynb b/examples/nblibrary/glc/Greenland_SMB_visual_compare_obs.ipynb similarity index 100% rename from examples/nblibrary/glc/LIWG_SMB_diagnostic.ipynb rename to examples/nblibrary/glc/Greenland_SMB_visual_compare_obs.ipynb