Contributing¶

Creating Issues¶

For bugs, open an issue in GitHub.

For features, provide enough context to illustrate the intended use case. If possible, include a test function that should pass once the feature is considered complete.

Developer setup¶

Clone the git repo and install kamodo in developer mode: from the base of the repo:

pip install -e .

Note

If you add any files while in editor mode, make sure they will be picked up by the MANIFEST.in file.

Kamodo is cross-platform, so you should be able work on whatever developing environment is convenient for you. However, we find it helpful to mount the code into a docker container and we provide a docker-compose.yaml. This causes the least disruption with your machine and makes it easier to deploy Kamodo containers to cloud services. If you have installed docker with docker compose, you can spin up a developer environment with one line from the base of the repo:

docker compose up

Creating a Pull Request¶

Want to contribute to Kamodo-core? Open a pull request!

Branching¶

First create a branch off of master, named after the feature or issue you are targeting.

git checkout -b issue-999

You may start your PR when you prefer, depending on how much support you'll need to complete it, but remember it should be up-to-date with master before it can be merged.

Testing¶

Run tests locally prior to pushing.

pip install pytest pytest-cov

Then, from the base of the git repo, run tests

pytest

or check code coverage with

PYTHONPATH=. coverage run -m pytest
coverage report -m

Generating Docs¶

Kamodo's documentation site is a good example of how to embed your own plots in your own website. The documentation site is generated by the mkdocs package with some addons

mkdocs - handles site generation and deployment (configured by top-level mkdocs.yaml)
mkdocs-material
mkdocs-jupyter
pymdown-extensions
mkdocs-include-markdown-plugin
mkdocstrings[python]

All of the requirements for mkdocs can be installed by using the requirements.txt file.

pip install -r requirements.txt

You can then generate the docs and serve locally with

mkdocs serve

To deploy your own documentation on github-pages:

mkdocs gh-deploy

This generates a gh-pages branch with the static site files and pushes it to github. Github automatically creates a website url based on that branch.

Upgrading¶

New versions of kamodo's dependencies will require periodic updates to the core package. The following steps should be followed to keep this package maintained.

Update github workflow
Create dockerfile
Update docker-compose.yml
Update pyproject.toml
Update pypi package

Update github workflow¶

In the base of this repo .github/workflows/kamodo-package.yml, edit the jobs section to reflect the intended versions of python to support

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]

Whenever a commit is pushed to this repo, all of the listed python versions will be tested. If any errors show up, this will reveal any changes we need so that all tests pass.

Create dockerfile¶

Builds with different base dependencies (such as python versions) require their own docker files. This allows developers to develop and test changes locally. Add the build to dockerfiles/<build-name>.Dockerfile. For example, an appropriate image for python 3.11 is in dockerfiles/kamodo-py311.Dockerfile.

Update docker-compose¶

Include runtime parameters for your upgrade in docker-compose.yml. For example, the following docker compose service can be run like this

docker compose up kamodo-py311 # builds and hosts a python-3.11 kamodo notebook server at localhost:8888

  kamodo-py311:
    image: ensemble/kamodo-py311
    platform: linux/arm64/v8 # aarch64-linux-gnu
    ports:
      - "8888:8888"
    build:
      context: .
      dockerfile: dockerfiles/kamodo-py311.Dockerfile
    volumes:
      - type: bind
        source: ${PWD}
        target: /kamodo
    command:
      - jupyter
      - notebook
      - /kamodo
      - --port=8888
      - --no-browser
      - --ip=0.0.0.0
      - --allow-root