Contributing Guidelines¶

Contributions are welcome from the community. Questions can be asked on the issues page. Before creating a new issue, please take a moment to search and make sure a similar issue does not already exist. If one does exist, you can comment (most simply even with just a +1) to show your support for that issue.

If you have direct contributions you would like considered for incorporation into the project you can fork this repository and submit a merge request for review.

For additional information, please see the USGS software development best practices guide and the USGS Code of Scientific Conduct.

The big picture guidelines are:

Submit changes via a pull request from a feature branch section on Merge Requests for more details.
We generally try to follow pep8 as much as possible.
Include doc strings for all public methods. We use the Google doc string style.
Please use black to format python code.
Use Python’s built-in exceptions as much as possible.

Merge Request Guidelines¶

Use concise, yet informative commit messages.
Rebase (if you know how) to provide an easy-to-follow history of changes in your branch.
Update the changelog (CHANGELOG.md) for significant changes into the “main” section.
Update docs if relevant.
Add unit tests for any new features.
Run the unit tests (we use pytest) prior to sending in your changes.

Commit Messages¶

Commit messages should begin with a one line concise yet informative summary. A blank line should separate the one line summary from any additional information. We strongly recommend using the following templates, in which the first starts with a commit type (in all caps) that indicates the type of changes in the commit.

For example, a commit related to documentation would look like:

DOCS: [one line description]

[Optional additional information]

We use the set of commit types from the angular project:

BUILD: Changes that affect the build system or external dependencies (e.g., pyrpoject.toml)
CI: Changes to our CI configuration files and scripts (e.g., .gitlab-ci.yml)
DOCS: Documentation only changes
FEAT: A new feature
FIX: A bug fix
PERF: A code change that improves performance
REFACTOR: A code change that neither fixes a bug nor adds a feature
STYLE: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
TEST: Adding missing tests or correcting existing tests

Rebasing¶

Danger

Rebasing can do permanent damage to your branch if you do not do it correctly. Practice on a scratch repository until you are comfortable with how rebasing works.

You can use rebasing to clean up the history of commits in a branch to make the changes easier to follow. Common reasons to rebase include:

squashing (combining) several closely related commits into a single commit,
reordering commits, especially to allow squashing, and
dropping (removing) commits related to debugging.

Releases¶

Create a release candidate branch with a name related to the release version like v1.2.1.rc0.
Update code.json, this is now automated with the esi-releases pacakge. For example, use the following command to increase the minor version number (options are “major”, “minor”, and “patch”):
```
releases minor
```
Update CHANGELOG.md to include the changes for this version. The goal is for the changelog to be kept up to date with each merge request, so this step should largely consist of creating a new section for this release and moving content into it from “main”.
Commit changes to the v1.2.1.rc0 branch.
Push the branch to your origin.
```
git push origin v1.2.1.rc0
```
Create a merge request in to upstream main, merge it, and rebase locally.
Create an annotated tag from main and push the tag upstream
```
git tag -a v1.2.1 -m "Version 1.2.1"
git push upstream v1.2.1
```
- This git push command is what triggers the “release” pipeline that includes the test, build, and deploy stages.
- Note that we cannot have a hyphen in the tag name.
- Also, if we end the tag name with “dev” then it will be build and uploaded to pypi as a pre-release version, which means that it will never be pip installed unless the user specifies the exact version of the pre-release.
- Maintainence note: the PYPI tokens are maintained in gitlab for the ESI group, under Settings then CI/CD, then Variables. These tokens are associated with the “pager_cicd” pypi service account.
Create release from tag in gitlab. Give it a release title like v1.2.1.
Copy/paste the relevant part of the changelog into the “describe this release” section.

Build Documentation¶

Some additional packages are required to build the documentation, which can be included with the doc install option, e.g.,

pip install .[doc]

Then the docs are built with

cd docs/
./makedocs.sh

Note that the script includes the follow arguments:

rebuild - Build documentation from a clean starting point.
update - Incremental build of the documentation. No cleaning.
clean_data - Remove all temporary data files generated when building the documentation.
clean_all - Remove all temporary data files and generated documentation.

Notes:

Never commit the built documentation files.
Remember that the notebooks run gmprocess code when you build the docs, so please be sure to check that the tutorials ran sucessfully.
The result of the tutorials will depend on your config file options, so I recommend having a project with the default config file set up and use that project when building the docs.