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, run:

make install

This command will:

  • Show the currently active Python environment.

  • Refuse to install into Conda base.

  • Offer an explicit install target: - Poetry virtual environment (recommended), - Conda environment named ploonetide-env, or - the current active environment, if it is not Conda base.

  • Install ploonetide in editable mode, so source-code changes are immediately reflected without reinstalling.

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

  • Install notebook tools used by developers, including jupyterlab, ipython, ipywidgets, and ipympl.

You can also choose the install target non-interactively:

make install INSTALL_BACKEND=poetry
make install INSTALL_BACKEND=conda
make install INSTALL_BACKEND=current

The supported values are poetry, conda, current, and skip.

Note

If you select the Conda option, activate the environment manually after creation:

conda activate ploonetide-env

You can override the Conda environment name and Python version:

make install INSTALL_BACKEND=conda CONDA_ENV_NAME=my-env CONDA_PYTHON=3.12

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 --open-browser --watch src/ploonetide docs/source docs/_build/html

It opens the browser automatically after the initial build completes and watches for changes in the documentation source and package source, including docstrings. Generated API and autosummary files are ignored by the live watcher so the preview does not repeatedly reload while Sphinx is creating those files. 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.

  • Notebook tools: the developer install includes JupyterLab and related notebook packages through the dev extra.

  • Conda base safety: make install refuses to install into Conda base. Choose the Poetry or Conda install target instead, or activate a dedicated environment before using INSTALL_BACKEND=current.

  • 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.