.. _contributing:

************
Contributing
************

This guide covers how to set up a development environment for contributing to
``scaldys-project`` itself: cloning, testing, linting, and publishing.

For extending ``scaldys-project`` with new modules, build steps, or a new
platform builder, see :ref:`extension_points` instead.

.. contents:: On this page
   :local:
   :depth: 2


Development Setup
=================

Clone the repository and create the virtual environment with `uv
<https://docs.astral.sh/uv/>`_::

    git clone https://github.com/scaldys/scaldys-project.git
    cd scaldys-project
    uv sync --group dev

This installs the package in editable mode together with all development
dependencies (pytest, ruff, pyright, Sphinx, mdformat, etc.).

Running the Tests
-----------------

Use the ``test`` command to run the full test suite the same way CI does.
The command displays the exact syntax being executed before starting the
tests::

    scaldys-project test

This is equivalent to::

    uv run pytest -v --durations=0 --cov --cov-report=xml

For a quicker local run with terminal coverage output::

    uv run pytest --cov=scaldys_project --cov-report=term-missing

Linting, Type Checking, and Formatting
----------------------------------------

Use the ``ci`` commands to run all quality checks locally.  These are
**check-only**: they detect problems but never modify files, mirroring the
GitHub Actions pipeline exactly. Each command logs the complete subprocess
syntax before execution::

    scaldys-project ci all          # run every step; continues on error
    scaldys-project ci lint         # ruff check only (Python lint)
    scaldys-project ci format       # ruff format --diff (check, no rewrite)
    scaldys-project ci typecheck    # pyright only (Python type check)
    scaldys-project ci markdown     # mdformat --check (check, no rewrite)
    scaldys-project ci doclint      # sphinx-lint on docs/ (RST lint)

Run these from the root of the ``scaldys-project`` repository.  If
``scaldys-project ci all`` passes, the GitHub Actions run will too.

When a ``ci`` step reports failures, use the corresponding ``format`` command
to fix the files in place::

    scaldys-project format python   # rewrite Python files with ruff format
    scaldys-project format markdown # rewrite Markdown files with mdformat
    scaldys-project format all      # rewrite both (continues on error)

After formatting, stage and commit the changes, then re-run ``ci all`` to
confirm everything is clean.

See :ref:`markdown_formatting_guide` for the full technical explanation of
how ``ci markdown`` and ``format markdown`` work, how target markdown files
are discovered (``README.md`` and MkDocs documentation), and how local behaviour
compares to GitHub Actions.

Building the Documentation Locally
------------------------------------

::

    uv run sphinx-build -b html docs/manual/source docs/manual/build/html

Or via the convenience wrapper::

    cd docs/manual && make html

Versioning, Building, and Publishing
--------------------------------------

For the complete release procedure — PyPI Trusted Publishing setup, GitHub
environment configuration, workflow files, version bump, and TestPyPI dry run
— see :ref:`publishing`.

Quick reference for a local build::

    uv build

Testing Changes Against a Consuming Project
--------------------------------------------

When developing a feature in ``scaldys-project``, you can validate it against
a real consuming project without publishing to PyPI.  From inside the consuming
project, point it at your local ``scaldys-project`` checkout::

    # From inside the consuming project
    uv add --dev "scaldys-project @ path/to/scaldys-project"

Or install in editable mode so any change to ``scaldys-project`` source is
picked up immediately without reinstalling::

    uv add --dev --editable "path/to/scaldys-project"


Reporting Issues
================

Please report bugs and feature requests on the GitHub issue tracker:

https://github.com/scaldys/scaldys-project/issues