Contribution guide

README.md

@@ -1,54 +1,11 @@
 ## Python Glacier Evolution Model (PyGEM)
 
-Overview: Python Glacier Evolution Model (PyGEM) is an open-source glacier evolution model coded in Python that models the transient evolution of glaciers. Each glacier is modeled independently using a monthly timestep. PyGEM has a modular framework that allows different schemes to be used for model calibration or model physics (e.g., climatic mass balance, glacier dynamics).
+Overview: The Python Glacier Evolution Model (PyGEM) is an open-source glacier evolution model coded in Python that models the transient evolution of glaciers. Each glacier is modeled independently using a monthly timestep. PyGEM has a modular framework that allows different schemes to be used for model calibration or model physics (e.g., climatic mass balance, glacier dynamics).
 
-Manual: Details concerning the model physics, installation, and running the model may be found [here](https://pygem.readthedocs.io/en/latest/).
+Documentation: details concerning the model installation, physics, and more may be found at [pygem.readthedocs.io](https://pygem.readthedocs.io/en/latest/).
 
 Usage: PyGEM is meant for large-scale glacier evolution modeling.  PyGEM<1.0.0 are no longer being actively being supported.
 
-***
-
-### Installation
-PyGEM can be downloaded from the Python Package Index ([PyPI](https://pypi.org/project/pygem/)).  We recommend creating a dedicated [Anaconda](https://anaconda.org/) environment to house PyGEM.
-```
-conda create --name <environment_name> python=3.12
-conda activate <environment_name>
-pip install pygem
-```
-This will install all PyGEM dependencies within your conda environment, and set up PyGEM command line tools to run core model scripts.
-
-***
-
-### Setup
-Following installation, an initialization script should to be executed.
-
-The initialization script accomplishes two things:
-1. Initializes the PyGEM configuration file *~/PyGEM/config.yaml*.  If this file already exists, an overwrite prompt will appear.
-2. Downloads and unzips a set of sample data files to *~/PyGEM/*, which can also be manually downloaded [here](https://drive.google.com/file/d/1Wu4ZqpOKxnc4EYhcRHQbwGq95FoOxMfZ/view?usp=drive_link).
-
-Run the initialization script by entering the following in the terminal:
-```
-initialize
-```
-
-***
-
-### Development
-Please report any bugs [here](https://github.com/PyGEM-Community/PyGEM/issues).
-
-If you are interested in contributing to further development of PyGEM, we recommend forking [PyGEM](https://github.com/PyGEM-Community/PyGEM) and then [cloning](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) onto your local machine.
-
-Note, if PyGEM was already installed via PyPI, first uninstall:
-```
-pip uninstall pygem
-````
-
-You can then use pip to install your locally cloned fork of PyGEM in 'editable' mode to easily facilitate development like so:
-```
-pip install -e /path/to/your/cloned/pygem/fork/
-```
-
-
 ***
 
 ### Model Testing

docs/contributing.md

@@ -0,0 +1,32 @@
+(contributing_pygem_target)=
+# PyGEM Contribution Guide
+## General
+- The branch `dev` is the repository's working branch and should (almost) always be the base branch of PRs. But exceptions exist: for example, hotfixes that need to be pushed to the `master` branch asap, updating the `README`, etc.
+- Do not push to other people's branches. Instead create a new branch and open a PR that merges your new branch into the branch you want to modify.
+
+## Issues
+- Check whether an issue describing your problem already exists [here](https://github.com/PyGEM-Community/PyGEM/issues).
+- Keep issues simple: try to describe only one problem per issue. Open multiple issues or sub-issues when appropriate.
+- Label the issue with the appropriate label (e.g., bug, documentation, etc.).
+- If you start working on an issue, assign it to yourself. No need to ask if you may assign it to yourself, unless there is someone already assigned to it.
+
+## Pull requests (PRs)
+- PRs should be submitted [here](https://github.com/PyGEM-Community/PyGEM/pulls).
+- PRs should be linked to an issue that it addresses (unless it's a really minor fix when it's not worth opening a new issue).
+- PRs should generally address only one issue. This helps PRs stay shorter, which makes it easier to review.
+- Concisely describe what your PR does. Avoid repeating what was already said in the issue.
+- Assign the PR to yourself.
+- First open a Draft PR. Then think:
+    - Did you make all changes you wanted to make?
+    - Did you add tests for all new functionalities you added?
+    - The test suite should be automatically run (you can see the progress of it in the Checks tab of the PR). Do all tests pass?
+
+  If the answer to all of the above is "yes", you can mark the PR as "Ready to review" and request a review from whoever you want to review it.
+- You will not be able to merge into `master` and `dev` branches without a reviewer's approval.
+
+### Reviewing PRs and responding to a review
+- Reviewers should leave comments on appropriate lines. 
+  - The original author of the PR should address all those comments by saying what they did and in what commit, so that it is easy to find. For example, a short response like "Fixed in commit https://github.com/PyGEM-Community/PyGEM/commit/ebddb9891efe60c747d3400b45627fb5d8e994f5" is often enough. 
+  - After responding to a reviewer's comment, do not mark it as resolved.
+  - Once you address all comments, request a new review from the same reviewer. That reviewer should look at all responses and resolve the comments that they are now happy with.
+- After you approve someone else's PR, do not merge it. Let the original author of the PR merge it when they are ready. They might notice last minute that more changes are necessary.

docs/index.rst

@@ -56,7 +56,7 @@ with respect to modeling glacier dynamics and ice thickness inversions.
    :maxdepth: 1
    :caption: Contributing:
 
-   dev
+   contributing
    citing
 
 .. Indices and tables

docs/install_pygem.md

@@ -1,29 +1,67 @@
 (install_pygem_target)=
-# Installing PyGEM
-The Python Glacier Evolution Model has been packaged using Poetry and is hosted on the Python Package Index ([PyPI](https://pypi.org/project/pygem/)), such that all dependencies should install seamlessly. It is recommended that users create a [Anaconda](https://anaconda.org/) environment from which to install the model dependencies and core code.
+# Installation
+The Python Glacier Evolution Model has been packaged using Poetry and is hosted on the Python Package Index ([PyPI](https://pypi.org/project/pygem/)), such that all dependencies should install seamlessly. It is recommended that users create a [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/index.html) environment from which to install the model dependencies and core code. If you do not yet have conda installed, see [conda's documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/install) for instructions.
 
-### Setup Conda Environment
-Anaconda is a Python dependency management tool. An Anaconda (conda) environment is essentially a directory that contains a specific collection of installed packages. The use of environments reduces issues caused by package dependencies. It is recommended that users first create conda environment from which to install PyGEM and its dependencies (if you do not yet have conda installed, see [conda's documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/install) for instructions).  We recommend a conda environment with python >=3.10, <3.13.
+Next, choose your preferred PyGEM installation option:<br>
+- [**stable**](stable_install_target): this is the latest version officially released and has a fixed version number (e.g. v1.0.1).
+- [**dev**](dev_install_target): this is the development version. It might contain new features and bug fixes, but is also likely to continue to change until a new release is made. This is the recommended way if you want to work with the latest changes to the code.
+- [**dev+**](dev+_install_target): this is the recommended way if you plan to contribute to the PyGEM and make your own changes to the code.
 
-A new conda environment can be created from the command line such as:
+```{note}
+The **dev** and **dev+** installation options require [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) software to be installed on your computer.
 ```
-conda create --name <environment_name> python=3.12
+**Copyright note**: PyGEM's installation instructions are modified from that of [OGGM](https://docs.oggm.org/en/stable/installing-oggm.html)
+
+(stable_install_target)=
+## Stable install
+The simplest **stable** installation method is to use an environment file. Right-click and save PyGEM's recommended environment file from [this link](https://github.com/PyGEM-Community/PyGEM/tree/master/docs/pygem_env.yml).
+
+From the folder where you saved the file, run `conda env create -f pygem_environment.yml`.
+```{note}
+By default the environment will be named `pygem`. A different name can be specified in the environment file.
+```
+
+(dev_install_target)=
+## Dev install
+Install the [development version](https://github.com/PyGEM-Community/PyGEM/tree/dev) of PyGEM in your conda environment using pip:
+```
+pip uninstall pygem
+pip install git+https://github.com/PyGEM-Community/pygem/@dev
+```
+
+(dev+_install_target)=
+## Dev+ install
+If you intend to access and make your own edits to the model, is is recommended that you clone the source code locally to your computer.
+
+Either clone [PyGEM's GitHub repository](https://github.com/PyGEM-Community/PyGEM) directly, or initiate your own fork to clone. See [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) for instructions on how to fork a repo.
+
+If PyGEM was already installed in your conda environment it is recommended that you first uninstall:
+```
+pip uninstall pygem
 ```
 
-### PyPI installation
-Ensure you've activated your PyGEM environment
+Next, clone PyGEM. This will place the code at your current directory, so you may wish to navigate to a desired location in your terminal before cloning:
 ```
-conda activate <environment_name>
+git clone https://github.com/PyGEM-Community/PyGEM.git
 ```
+If you opted to create your own fork, clone using appropriate repo URL: `git clone https://github.com/YOUR-USERNAME/PyGEM.git`
 
-Next, install PyGEM via [PyPI](https://pypi.org/project/pygem/):
+Navigate to root project directory:
 ```
-pip install pygem
+cd pygem
 ```
 
-This will install all PyGEM dependencies within your conda environment, and set up PyGEM command line tools to run core model scripts.
+Install PyGEM in 'editable' mode:
+```
+pip install -e .
+```
+
+Installing a package in editable mode (also called development mode) creates a symbolic link to your source code directory (*/path/to/your/PyGEM/clone*), rather than copying the package files into the site-packages directory. This allows you to modify the package code without reinstalling it. Changes to the source code take effect immediately without needing to reinstall the package, thus efficiently facilitating development.<br>
+
+To contribute to PyGEM's development, see the [contribution guide](contributing_pygem_target).
 
-### Setup
+(setup_target)=
+# Setup
 Following installation, an initialization script should to be executed.
 
 The initialization script accomplishes two things:
@@ -35,5 +73,5 @@ Run the initialization script by entering the following in the terminal:
 initialize
 ```
 
-### Demonstration Notebooks
-A series of accompanying Jupyter notebooks have been produces for demonstrating the functionality of PyGEM. These can be acquired and installed from [GitHub](https://github.com/PyGEM-Community/PyGEM-notebooks).
+# Demonstration Notebooks
+A series of accompanying Jupyter notebooks have been produced for demonstrating the functionality of PyGEM. These can be acquired from [GitHub](https://github.com/PyGEM-Community/PyGEM-notebooks).

docs/pygem_environment.yml

@@ -0,0 +1,6 @@
+name: pygem
+dependencies:
+  - python>=3.10,<3.13
+  - pip
+  - pip:
+    - pygem