Contributing¶

Creating Issues¶

For bugs, open an issue following this guide.

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 .

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.

python -m pip install flake8 pytest
pip install pytest-cov

Then, from the base of the git repo

pytest --cov kamodo.kamodo --cov kamodo.util --cov plotting kamodo/test_plotting.py kamodo/test_kamodo.py kamodo/test_utils.py

Try to at least maintain the current code coverage with your PR.

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)
• markdown-include - allows for embedding of markdown files (and graph divs) outside the docs folder
• python-markdown-math - enables LaTeX rendering
• mknotebooks - allows for the embedding of jupyter notebooks

All of the above requirements can be installed with this line:

pip install mkdocs python-markdown-math markdown-include mknotebooks

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.

Releasing¶

Kamodo uses calendar versioning via incremental:

pip install incremental

To update the package

cd kamodo # navigate from base of repo into package
python -m incremental.update versioning # assigns a new (calender) version number within module 
# python -m incremental.update versioning --rc # for release candidate
git add versioning # stage version update
hourly commit.message="version update, other features here" # commit version update (optional)
cd .. # navigate back to base of repo
pip install -e . # update local version
git tag version_number_here # create new tag
git push origin version_number_here # triggers pypi update (requires adequate github permissions)

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.

1. Update github workflow
2. Create dockerfile
3. Update docker-compose.yml
4. Update setup.cfg
5. Update pypi package

Update github workflow¶

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

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']

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

Hourly (optional)¶

Consider using hourly for time tracking your branch. This will allow future developers to see which parts of the code receive the most attention.

If you're using hourly, you'll want to configure hourly.yaml so that your worklog points to a file named after you:

work_log:
  header_depth: 3
  filename: worklogs/my_github_username.md