Contributing#
This document contains guidelines for the collaboration in the glacier-flow-model python package.
Getting started#
Ready to contribute? Here’s how to set up glacier-flow-model for local development.
Clone the repository:
git clone https://github.com/munterfi/glacier-flow-model.gitInstall the dependencies:
poetry installCreate a feature branch for local development:
git checkout -b feature/<the-feature-name> master- Work locally on the feature, make sure to add or adjust:
entries in CHANGELOG.md
docstrings
tests for the feature
documentation
When finished with the feature, check that the changes pass:
poetry run pytest # Running tests
poetry run mypy . # Static type checks
poetry run flake8 glacier_flow_model tests # Code linting
cd docs && poetry run make html && cd .. # Build documentation
Alternatively the script check.sh automates the steps above.
If tests are passed commit and push the changes:
git add .
git commit -m "Description of the changes."
git push origin feature/<the-feature-name>
Submit a pull request of the feature into the
masterbranch on GitHub.
Trunk-based Development Workflow#
The trunk-based development workflow uses one branch master to record the history of the project.
In addition to the mainline short-lived feature or bugfix branches are used to develop new features or fix bugs.
Features#
Each new feature should reside in its own short-lived branch. Branch off of a feature/<feature-description> branch from master.
When a feature is complete, it gets merged back into master and the feature branch is deleted.
Bugfix#
Each bugfix should reside in its own short-lived branch. Branch off of a bugfix/<bugfix-description> branch from master.
When the fix is complete, it gets merged back into master and the bugfix branch is deleted.
Release#
This packages uses semantic versioning. Once master has acquired enough features for a release,
set the new version number of the in the pyproject.toml and the CHANGELOG:rst file. Commit and push to master
and publish a new release on GitHub, which will trigger an action to build
and publish the package to PyPi.
Dependencies#
Dependencies and virtual environments are managed by poetry, do not edit the requirements manually!
E.g. use poetry update && poetry build for version updating and poetry add <package_1> <package_2> for adding new ones.
Documentation and coding style#
Naming convention#
Use snake_case for variable, argument and function/method name definitions.
Also in tables that are written to the database avoid capital letters and
dots (.) in column name definitions. For class names use UpperCaseCamelCase.
Python docstrings#
Create python documentation with docstrings in numpydoc convention.
Example:
def function_with_types_in_docstring(param1: str, param2: int = 10):
"""Example function with types documented in the docstring.
`PEP 484`_ type annotations are supported. If attribute, parameter, and
return types are annotated according to `PEP 484`_, they do not need to be
included in the docstring:
Parameters
----------
param1 : str
The first parameter.
param2 : int, default 10
The second parameter.
Returns
-------
bool
True if successful, False otherwise.
.. _PEP 484:
https://www.python.org/dev/peps/pep-0484/
"""
Script header template#
Add a header to CLI scripts according to the following template:
#!/usr/bin/env bash
# -----------------------------------------------------------------------------
# Name :example_script.sh
# Description :Short description of the scripts purpose.
# Author :Full name <your@email.ch>
# Date :YYYY-MM-DD
# Version :0.1.0
# Usage :./example_script.sh
# Notes :Is there something important to consider when executing the
# script?
# =============================================================================
Credits#
Depending on the scope of your contribution add yourself to the authors field in the pyproject.toml file
to ensure credits are given correctly.