Contributing

PlestyLib is developed under the PLESTY governance rules, in the governance repository. This page is the short version for plesty-lib; the PLESTY Contributor Guide walks through the whole workflow, and the module registry lists the modules built on plesty-lib.

Issues and merge requests live on gitlab.com/plesty/core/plesty-lib.

Before you start

• Every change has an issue. Open one first, or pick an existing one.

• A new feature is agreed before it is written: its scope, its interface and where it fits are settled with the Product Owner in the issue. A bug fix or a documentation change can start straight away.

The three branches

plesty-lib keeps three kinds of long-lived branch, called lines. You never work on a line directly: you make a branch from one, and it comes back through a merge request.

Line	Holds	Written by
main	the newest release: what a clone gets, and what these docs publish as latest	the release merge only
exp	what the next release (the next MINOR version) will be	merge requests of features, and of fixes carried up
maintain/<major>.<minor>, such as maintain/0.4	one supported release line, for fixes only	merge requests of fixes

Two lines are supported at a time: the current one and the one before it. A feature never goes into a maintain/* line, which is what makes staying on an older version safe.

Which line your change starts from

Your change	Start from
a new feature, or a change of shape (feat, refactor)	exp
a bug fix (fix)	the oldest supported line that has the bug; it is then merged upward into the newer lines, never copied downward
documentation, tests, CI, housekeeping (docs, test, ci, chore)	exp, unless it repairs a supported line

Name the branch <type>/<what it does>, such as fix/reconnect-after-timeout or docs/quickstart-analyzer, and open the merge request into the line you started from:

git checkout exp && git pull --ff-only origin exp
git checkout -b feat/my-change
# ... work, commit ...
git push -u origin feat/my-change    # then open a merge request into exp

Checks

Every change must pass plesty check, the checking command of plesty-sdk, at the quantum standard that plesty-lib uses: formatting, types, docstrings, tests, licensing, dependency security, the docs build and more.

uv run plesty check

The same check runs as a hook before every git push, and again in CI on every merge request; a failing check blocks the merge.

• Format with plesty-sdk’s own settings. Plain ruff format uses a different line length and fails the check:

  uv run ruff format --config $(uv run python -c "from importlib.resources import files; print(files('plesty.sdk').joinpath('assets/ruff.toml'))") .
  

• The public API does not change in a patch release. Everything whose name does not start with _ is public. Gate 8 of plesty check compares it with the last release, so a fix that changes the public API fails there; such a change belongs in the next MINOR version, through exp.

• New code has tests, and the existing tests keep passing.

What goes with a change

• The changelog. Add an entry under ## Unreleased in CHANGELOG.md, in the same commit, for anything a user would notice. A breaking change says what to change, and a deprecation names its replacement and the version that removes it.

• The docs. Update the pages under docs/ that describe what you changed. A change to how plesty-lib is built also updates Concepts: the layers in Packages and Layers, the promises in Interface Contracts, the reasoning in Design Decisions, and a new required package in Dependencies.

• Licensing. plesty-lib follows the REUSE standard: every Python file starts with SPDX lines naming its copyright, license and contributors. Add a SPDX-FileContributor line with your name to the files you change.