Skip to content

Commit f15c3a6

Browse files
btobersbtobers
committed
Contribution guide added to PyGEM docs
Closes #51. Contribution guided added to documentation. PyGEM installation instructions expanded upon. `pygem_environment.yml` file created for simple install.
1 parent 49aa43f commit f15c3a6

7 files changed

Lines changed: 93 additions & 83 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,10 @@
11
## Python Glacier Evolution Model (PyGEM)
22

3-
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).
3+
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).
44

5-
Manual: Details concerning the model physics, installation, and running the model may be found [here](https://pygem.readthedocs.io/en/latest/).
6-
7-
Usage: PyGEM is meant for large-scale glacier evolution modeling. PyGEM<1.0.0 are no longer being actively being supported.
8-
9-
***
10-
11-
### Installation
12-
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.
13-
```
14-
conda create --name <environment_name> python=3.12
15-
conda activate <environment_name>
16-
pip install pygem
17-
```
18-
This will install all PyGEM dependencies within your conda environment, and set up PyGEM command line tools to run core model scripts.
19-
20-
***
21-
22-
### Setup
23-
Following installation, an initialization script should to be executed.
24-
25-
The initialization script accomplishes two things:
26-
1. Initializes the PyGEM configuration file *~/PyGEM/config.yaml*. If this file already exists, an overwrite prompt will appear.
27-
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).
28-
29-
Run the initialization script by entering the following in the terminal:
30-
```
31-
initialize
32-
```
33-
34-
***
35-
36-
### Development
37-
Please report any bugs [here](https://github.com/PyGEM-Community/PyGEM/issues).
38-
39-
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.
40-
41-
Note, if PyGEM was already installed via PyPI, first uninstall:
42-
```
43-
pip uninstall pygem
44-
````
45-
46-
You can then use pip to install your locally cloned fork of PyGEM in 'editable' mode to easily facilitate development like so:
47-
```
48-
pip install -e /path/to/your/cloned/pygem/fork/
49-
```
5+
Details concerning the model installation, physics, and more may be found at [pygem.readthedocs.io](https://pygem.readthedocs.io/en/latest/).
506

7+
PyGEM versions prior to 1.0.0 are no longer actively supported.
518

529
***
5310

‎docs/contributing.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
(contributing_pygem_target)=
2+
# PyGEM Contribution Guide
3+
4+
Before contributing to PyGEM, it is recommended that you either clone [PyGEM's GitHub repository](https://github.com/PyGEM-Community/PyGEM) directly, or initiate your own fork (as described [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)) to then clone.
5+
6+
If PyGEM was already installed in your conda environment (as outlined [here](install_pygem_target)), it is recommended that you first uninstall:
7+
```
8+
pip uninstall pygem
9+
```
10+
11+
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:
12+
```
13+
git clone https://github.com/PyGEM-Community/PyGEM.git
14+
```
15+
If you opted to create your own fork, clone using appropriate repo URL: `git clone https://github.com/YOUR-USERNAME/PyGEM.git`
16+
17+
Navigate to root project directory:
18+
```
19+
cd PyGEM
20+
```
21+
22+
Install PyGEM in 'editable' mode:
23+
```
24+
pip install -e .
25+
```
26+
27+
Installing a package in editable 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.<br>
28+
29+
## General
30+
- The `dev` branch is the repository's working branch and should almost always be the base branch for Pull Requests (PRs). Exceptions include hotfixes that need to be pushed to the `master` branch immediately, or updates to the `README`.
31+
- 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.
32+
33+
## Issues
34+
- Check whether an issue describing your problem already exists [here](https://github.com/PyGEM-Community/PyGEM/issues).
35+
- Keep issues simple: try to describe only one problem per issue. Open multiple issues or sub-issues when appropriate.
36+
- Label the issue with the appropriate label (e.g., bug, documentation, etc.).
37+
- If you start working on an issue, assign it to yourself. There is no need to ask for permission unless someone is already assigned to it.
38+
39+
## Pull requests (PRs)
40+
- PRs should be submitted [here](https://github.com/PyGEM-Community/PyGEM/pulls).
41+
- PRs should be linked to issues they address (unless it's a minor fix that doesn't warrant a new issue). Think of Issues like a ticketing system.
42+
- PRs should generally address only one issue. This helps PRs stay shorter, which in turn makes the review process easier.
43+
- Concisely describe what your PR does. Avoid repeating what was already said in the issue.
44+
- Assign the PR to yourself.
45+
- First, open a Draft PR. Then consider:
46+
- Have you finished making changes?
47+
- Have you added tests for all new functionalities you introduced?
48+
- Have all tests passed in the CI? (Check the progress in the Checks tab of the PR.)
49+
50+
If the answer to all of the above is "yes", mark the PR as "Ready for review" and request a review from an appropriate reviewer. If in doubt of which reviewer to assign, assign [drounce](https://github.com/drounce).
51+
- You will not be able to merge into `master` and `dev` branches without a reviewer's approval.
52+
53+
### Reviewing PRs and responding to a review
54+
- Reviewers should leave comments on appropriate lines. Then:
55+
- The original author of the PR should address all comments, specifying what was done and in which commit. For example, a short response like "Fixed in [link to commit]." is often sufficient.
56+
- After responding to a reviewer's comment, do not mark it as resolved.
57+
- Once all comments are addressed, request a new review from the same reviewer. The reviewer should then resolve the comments they are satisfied with.
58+
- After approving someone else's PR, do not merge it. Let the original author of the PR merge it when they are ready, as they might notice necessary last-minute changes.

‎docs/dev.md‎

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎docs/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ with respect to modeling glacier dynamics and ice thickness inversions.
5656
:maxdepth: 1
5757
:caption: Contributing:
5858

59-
dev
59+
contributing
6060
citing
6161

6262
.. Indices and tables

‎docs/install_pygem.md‎

Lines changed: 24 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,35 @@
11
(install_pygem_target)=
2-
# Installing PyGEM
3-
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.
2+
# Installation
3+
The Python Glacier Evolution Model has been packaged using Poetry and is hosted on the Python Package Index ([PyPI](https://pypi.org/project/pygem/)), to ensure that all dependencies 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.
44

5-
### Setup Conda Environment
6-
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.
5+
Next, choose your preferred PyGEM installation option:<br>
6+
- [**stable**](stable_install_target): this is the latest version that has been officially released to PyPI, with a fixed version number (e.g. v1.0.1). It is intended for general use.
7+
- [**development**](dev_install_target): this is the development version of PyGEM hosted on [GitHub](https://github.com/PyGEM-Community/PyGEM/tree/dev). 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 option if you want to work with the latest changes to the code. Note, this installation options require [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) software to be installed on your computer.
78

8-
A new conda environment can be created from the command line such as:
9-
```
10-
conda create --name <environment_name> python=3.12
11-
```
9+
**Copyright note**: PyGEM's installation instructions are modified from that of [OGGM](https://docs.oggm.org/en/stable/installing-oggm.html)
1210

13-
### PyPI installation
14-
Ensure you've activated your PyGEM environment
15-
```
16-
conda activate <environment_name>
11+
(stable_install_target)=
12+
## Stable install
13+
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).
14+
15+
From the folder where you saved the file, run `conda env create -f pygem_environment.yml`.
16+
```{note}
17+
By default the environment will be named `pygem`. A different name can be specified in the environment file.
1718
```
1819

19-
Next, install PyGEM via [PyPI](https://pypi.org/project/pygem/):
20+
(dev_install_target)=
21+
## Development install
22+
Install the [development version](https://github.com/PyGEM-Community/PyGEM/tree/dev) of PyGEM in your conda environment using pip:
2023
```
21-
pip install pygem
24+
pip uninstall pygem
25+
pip install git+https://github.com/PyGEM-Community/pygem/@dev
2226
```
2327

24-
This will install all PyGEM dependencies within your conda environment, and set up PyGEM command line tools to run core model scripts.
28+
If you intend to access and make your own edits to the model's source code, see the [contribution guide](contributing_pygem_target).
2529

26-
### Setup
27-
Following installation, an initialization script should to be executed.
30+
(setup_target)=
31+
# Setup
32+
Following installation, an initialization script should be executed.
2833

2934
The initialization script accomplishes two things:
3035
1. Initializes the PyGEM configuration file *~/PyGEM/config.yaml*. If this file already exists, an overwrite prompt will appear.
@@ -35,5 +40,5 @@ Run the initialization script by entering the following in the terminal:
3540
initialize
3641
```
3742

38-
### Demonstration Notebooks
39-
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).
43+
# Demonstration Notebooks
44+
A series of accompanying Jupyter notebooks has been produced for demonstrating the functionality of PyGEM. These are hosted in the [PyGEM-notebooks repository](https://github.com/PyGEM-Community/PyGEM-notebooks).

‎docs/pygem_environment.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
name: pygem
2+
dependencies:
3+
- python>=3.10,<3.13
4+
- pip
5+
- pip:
6+
- pygem

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[tool.poetry]
22
name = "pygem"
3-
version = "1.0.1"
3+
version = "1.0.2"
44
description = "Python Glacier Evolution Model (PyGEM)"
55
authors = ["David Rounce <drounce@cmu.edu>,Brandon Tober <btober@cmu.edu>"]
66
license = "MIT License"

0 commit comments

Comments
 (0)