Contribution Workflow¶
This document describes the typical workflow for contributing to Otterdog.
Getting the source code¶
Fork the repository¶
Fork the repository on GitHub and clone your fork locally.
Add a git remote¶
Add a remote and regularly sync to make sure you stay up-to-date with our repository:
git remote add upstream https://github.com/eclipse-csi/otterdog
git checkout main
git fetch upstream
git merge upstream/main
Prepare development environment¶
Install otterdog development Python dependencies
See Development Setup for more details.
Pre-commit hooks¶
The project extensively uses pre-commit hooks to ensure consistent source code formatting and type checking.
To enable pre-commit run the following:
Check out a new branch and make your changes¶
Create a new branch for your changes.
# Checkout a new branch and make your changes
git checkout -b my-new-feature-branch
# Make your changes...
Run tests¶
Run tests locally to make sure everything is working as expected.
Note: Code coverage HTML is also available in htmlcov/
Write docs¶
Otterdog docs are built with mkdocs and
material. Check out their docs
for specific Markdown flavors.
Relevant sources are:
docs/: Site contentsmkdocs.yml: Site config.readthedocs.yaml: Deployment config
Please always review your changes locally (some things render differently, than you might be used from GitHub):
Commit and push your changes¶
Commit your changes, push your branch to GitHub, and create a pull request.
Please follow the pull request template and fill in as much information as possible. Link to any relevant issues and include a description of your changes.
When your pull request is ready for review, add a comment with the message "please review" and we'll take a look as soon as we can.
Pull Requests¶
It should be extremely simple to get started and create a Pull Request.
Unless your change is trivial (typo, docs tweak etc.), please create an issue to discuss the change before creating a pull request.
If you're looking for something to get your teeth into, check out the "help wanted" label on GitHub.
To make contributing as easy and fast as possible, you'll want to run tests and linting locally. Luckily, Otterdog has few dependencies, doesn't require compiling and tests don't need access to databases, etc. Because of this, setting up and running the tests should be very simple.