Developer Guide

This guide is for developers working on ploonetide. It explains how to set up a development environment, use the provided Makefile utilities, and follow best practices when contributing.

Environment Setup

To get started, simply run:

make install

This command will:

  • Check if Poetry is installed. If not, it installs Poetry automatically using pip.

  • Detect whether you already have an active virtual environment.

  • If no environment is active: - It offers to create a new Poetry environment (recommended), or - Creates a Conda environment named ploonetide-env using the exported dependencies from pyproject.toml.

  • Install ploonetide in editable mode, so that changes to the source code are immediately reflected without reinstallation.

  • Install all core and development dependencies inside the selected environment.

  • Automatically clean up temporary Conda export files (conda_environment.yml, conda_requirements.txt).

Note

If you select the Conda option, you will still need to activate the environment manually after creation:

conda activate ploonetide-env

Makefile Commands

The Makefile provides shortcuts for common development tasks:

Environment and Installation - make install – Full setup: environment creation + dependency installation - make env – Show environment status

Code Quality and Testing - make all – Run static analysis and tests (mypy, pytest, flake8) - make pytest – Run tests - make coverage – Generate test coverage report - make flake8, make mypy, make black, make isort – Run individual quality tools - make lint – Shortcut for flake8 + mypy - make format – Format code (black + isort) - make check-format – Check if formatting is correct

Versioning - make bump – Bump patch version - make bump-minor – Bump minor version - make bump-major – Bump major version - make release – Push the current branch and matching version tag to GitHub after confirmation

Release Workflow

Before creating a release, make sure all intended code, documentation, and test changes are committed. The bump commands create a dedicated version commit and Git tag, so the working tree should be clean before running them.

Recommended release sequence:

make clean
make pytest
poetry check
git status
git add <changed-files>
git commit -m "Prepare release"
make bump-minor
make release

Use make bump for a patch release, make bump-minor for a minor release, and make bump-major for a major release. Tags are created from the version string in pyproject.toml (for example, 1.1.0).

Documentation - make docs – Launch a live-reloading preview of the documentation at http://127.0.0.1:8000

This command uses:

sphinx-autobuild docs/source docs/_build/html

It opens the browser automatically and watches for changes in the documentation source. This does not interfere with your existing conf.py or the ReadTheDocs build process.

All required documentation tools (sphinx, sphinx-autobuild, myst-parser, numpydoc) are included in the [tool.poetry.group.dev.dependencies] section of pyproject.toml, so no additional installation is necessary for contributors.

Maintenance - make clean – Remove temporary and build artifacts - make export-conda-env – Export conda_environment.yml directly from pyproject.toml

Important Notes

  • Editable installation: ploonetide is installed in editable mode, so any changes to the codebase are immediately usable without reinstalling.

  • poetry.lock: This file is generated automatically when running make install with Poetry. It is not required for collaborative development and will be automatically removed by make clean.

  • Clean PRs: Before pushing to GitHub, always run:

    make clean

    This ensures that autogenerated or temporary files (e.g., poetry.lock, conda_requirements.txt, conda_environment.yml, etc.) are removed and do not clutter your pull request.

Questions?

If you need help with setup, versioning, or anything else related to development, please open an issue or contact the maintainers.