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.

git clone https://github.com/<your username>/otterdog.git
cd otterdog

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

make init

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:

poetry run prek install

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.

# Run tests
make test

Note: Code coverage HTML is also available in htmlcov/

The end-to-end tests of the Playground of the dashboard, in tests/webapp/playground/, run in Firefox with Playwright. They are skipped unless the assets of the webapp are built and Firefox is installed, which make init does:

(cd otterdog/webapp/static && npm ci && npm run build)
poetry run pytest tests/webapp/playground

The scripts of the Playground also have unit tests, run with npm test in otterdog/webapp/static.

Write docs¶

Otterdog docs are built with Zensical, check out its docs for specific Markdown flavors (admonitions, content tabs, code annotations, snippets).

Relevant sources are:

docs/: Site contents
zensical.toml: Site config (navigation, theme, Markdown extensions)
docs-theme/ and docs/assets/theme.css: Theme overrides (Eclipse colors, hero of the home page)
docs_site.py: Staging of the site for Zensical (playground links, settings from the environment)
.github/workflows/docs.yml: Build and preview of every pull request, deployment of main to GitHub Pages
.github/workflows/docs-preview.yml: Removal of the preview of a pull request when it is closed

Please always review your changes locally (some things render differently, than you might be used from GitHub):

make docs-serve              # live preview on http://127.0.0.1:8000/
make docs                    # strict build into site/, broken links and anchors fail

Every pull request that changes the documentation is built strictly. When it comes from a branch of the repository, its preview is published at https://csi.eclipse.dev/otterdog-website-preview/pr-preview/pr-<number>/, and a comment on the pull request links it. The pull requests from forks are built without a preview: they have no access to the token that publishes it.

Complete jsonnet examples, i.e. examples that define an organization with orgs.newOrg without omitting content with ... or using placeholders like <github-id>, get a link that opens them in the Playground of an otterdog dashboard. The link is added by docs_playground.py when docs_site.py stages the site, the url of the dashboard is set by the environment variable OTTERDOG_URL (https://otterdog.eclipse.org by default, an empty value omits the links):

OTTERDOG_URL=https://otterdog.example.org make docs-serve

To target the webapp of your development environment, use make docs-serve-dev, make docs-serve-tunnel or make docs-serve-ngrok, see Test the Playground with the documentation.

The jsonnet examples of the Configuration Guides must be complete: the test tests/test_docs_examples.py validates each of them against the example default configuration.

The Playground of the dashboard lists these examples from a catalog generated from the guides, and describes the properties that it completes from a catalog generated from the Reference, i.e. from the property tables of its pages and from their "Jsonnet Function" sections. After changing an example or the reference, update both catalogs, otherwise tests/test_docs_playground.py fails:

make playground-examples

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.