From e5f67d1cd7655effd920991e3664e1645deda744 Mon Sep 17 00:00:00 2001
From: Austin Raney <austin.raney@noaa.gov>
Date: Wed, 7 Aug 2024 10:44:46 -0400
Subject: [PATCH] doc: update contribution guidance

---
 CONTRIBUTING.md | 112 +++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 106 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0f109b26..266c6710 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,9 +24,109 @@ guidance below.
 
 ## Changing the code-base
 
-Generally speaking, you should fork this repository, make changes in your
-own fork, and then submit a pull request. All new code should have associated
-unit tests that validate implemented features and the presence or lack of defects.
-Additionally, the code should follow any stylistic and architectural guidelines
-prescribed by the project. In the absence of such guidelines, mimic the styles
-and patterns in the existing code-base.
+All new code should have associated unit tests that validate implemented features and the presence or lack of defects.
+Additionally, the code should follow any stylistic and architectural guidelines prescribed by the project.
+In the absence of such guidelines, mimic the styles and patterns in the existing code-base.
+
+In general, we suggest contributors fork the repository, create a new branch, and submit a
+[PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
+This consists of three main steps:
+
+1. Fork, Clone, and Branch (`git` related things)
+2. Setup development environment and develop
+3. Open a pull request
+
+### Fork, Clone, and Branch
+
+1. [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) repository.
+   This creates a copy for yourself under your username and is done on GitHub.
+
+2. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) your fork.
+   Make a local copy of your fork.
+
+   ```bash
+   git clone git@github.com:{{ user.name }}/ngen-cal.git && cd ngen-cal
+   ```
+
+3. Create a new branch.
+   Open a new branch off of `master` for which you will work
+
+   ```bash
+   git checkout -b new_feature_branch
+   ```
+
+### Setup development environment and develop
+
+1. Setup and activate python virtual environment
+
+```bash
+# Create virtual environment
+python -m venv venv
+# Activate virtual environment
+source ./venv/bin/activate
+```
+
+2. Setting up `git` `pre-commit` hooks
+
+[`pre-commit`](https://pre-commit.com/) is used to manage and install `git` `pre-commit` hooks.
+`pre-commit` hooks run automatically when `git commit` is invoked and perform checks on the code you are committing.
+Example checks are removing trailing white spaces, verifying that large files are not included, or running a code linting tool.
+Hooks are configured in the [`.pre-commit-config.yaml`](./.pre-commit-config.yaml) file in the root of the repo.
+
+`pre-commit` can be installed using a package manager (e.g. `brew install pre-commit`) or from `pip` (e.g. `pip install pre-commit`).
+
+Install `pre-commit` hooks into your `git` clone by running:
+
+```bash
+pre-commit install
+```
+
+Hooks will now run when code is committed.
+Alternatively, you can run the pre-commit hooks manually via:
+
+```bash
+pre-commit run --all-files
+```
+
+For more information, see [`pre-commit`'s documentation](https://pre-commit.com/index.html).
+
+3. Install development version of package(s)
+
+```bash
+# installing ngen.cal
+pip install -e 'python/ngen_cal[develop]'
+
+# installing ngen.config
+pip install -e 'python/ngen_conf[develop]'
+
+# installing ngen.init_config
+pip install -e 'python/ngen_init_config[develop]'
+
+# installing ngen.config_gen
+pip install -e 'python/ngen_config_gen[develop]'
+```
+
+3. Develop
+
+We recommend commit messages follow
+[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)
+style.
+This is not a requirement, but adherence is appreciated :).
+
+
+### Open A Pull Request
+
+After pushing changes to your fork you are ready to start the PR process!
+First time submitters may find
+[this](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)
+guide helpful.
+
+Before you submit a pull request, please verify that you meet the guidelines outlined in
+[`PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md).
+Additionally, the following guidelines should also be met:
+
+1. If the pull request introduces code or changes to existing code, tests should be included.
+   Tests should be written so they are runnable by `pytest`.
+   It is recommended that first time submitters view existing tests to get started.
+2. Pull requests must pass all GitHub Actions.
+3. Usage of non-standard python packages should be kept to a minimum.