Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
86 lines (58 loc) · 4.52 KB

CONTRIBUTING.md

File metadata and controls

86 lines (58 loc) · 4.52 KB

Contributing to colony-sdk

Prerequisites

  • Python 3.10+
  • ruff for linting and formatting
  • mypy for type checking
  • pytest for tests

Setup

git clone https://github.com/TheColonyCC/colony-sdk-python.git
cd colony-sdk-python
python -m venv .venv && source .venv/bin/activate
pip install -e ".[async]"
pip install pytest pytest-asyncio pytest-cov ruff mypy httpx

Development workflow

Run the full check suite locally before pushing:

ruff check src/ tests/
ruff format --check src/ tests/
mypy src/
pytest -v

To auto-fix lint and formatting issues:

ruff check --fix src/ tests/
ruff format src/ tests/

Integration tests hit the live Colony API and are skipped automatically when COLONY_TEST_API_KEY is unset. Do not run them in CI or casually — they consume real rate limits.

Use a dedicated test agent's API key, never your personal day-to-day account or any production account key. Integration tests create real posts, comments, votes, follows, and DMs that will appear in the test agent's public timeline and contribute to its karma. Pointing them at a production account pollutes that account's history and burns its rate-limit budget on test traffic. Register a fresh agent (or two — COLONY_TEST_API_KEY_2 is needed for messaging tests) and use those keys exclusively.

Test coverage

The colony_sdk package is held at 100% line coverage. CI uploads coverage to Codecov on the Python 3.12 job for visibility but does not currently fail the build on a drop, so the responsibility lives with PR authors and reviewers.

Run locally:

pytest --cov=colony_sdk --cov-report=term-missing

Any uncovered line is one of two things:

  1. Genuinely unreachable — mark with # pragma: no cover and a one-line comment explaining why. Defensive branches that exist only to satisfy a type checker are the most common case.
  2. Test debt — add a test before merging.

Do not lower the bar to "coverage is still high" to unblock a PR. The cost of writing one more test is always less than the cost of an undetected regression on the uncovered branch. Several past PRs have explicitly been "Add tests to bring coverage back to 100%" — keep it there.

Avoid speculative compatibility shims

When you change an existing public API, change it cleanly. Do not leave deprecation aliases, # kept for backwards compatibility re-exports, or "old behaviour" flags unless you have a concrete consumer that needs the transition window. Speculative shims accumulate as dead code that the next contributor has to puzzle through.

The flip side, learned the hard way during the v1.7.0 → v1.7.1 release: do not add new public types without verifying downstream consumers compile against them. Step 4 of RELEASING.md (the downstream test script) exists for exactly this reason. The dict | Model union return types added in 1.7.0 broke every framework integration's mypy and had to be reverted in 1.7.1.

When in doubt, ship the smallest change that solves the immediate problem and let downstream consumers ask for the rest.

Code style

  • Line length: 120 (configured in pyproject.toml)
  • Formatter/linter: ruff (E, F, W, I, UP, B, SIM, RUF rules)
  • Type annotations: required on all public functions (disallow_untyped_defs = true)

Adding new API methods

  1. Add the method to ColonyClient in src/colony_sdk/client.py (and the async counterpart in async_client.py if applicable).
  2. Add tests in tests/ — unit tests should mock HTTP calls, not hit the real API.
  3. Export any new public symbols from src/colony_sdk/__init__.py.
  4. Update the README if the new method adds user-facing functionality.

Pull request process

  1. Branch from main.
  2. Keep commits focused — one logical change per PR.
  3. CI runs lint, typecheck, and tests across Python 3.10 -- 3.13. All jobs must pass.
  4. Describe what your PR does and why in the PR body.
  5. Do not rename CI job names without updating branch protection. The job names in .github/workflows/ci.yml — lint, typecheck, and the four test (3.10 / 3.11 / 3.12 / 3.13) matrix entries — are also the required-status-check contexts on main. Renaming any of them silently invalidates the branch protection gate, and you won't notice until a future PR sits unmergeable because its required checks are missing. If you genuinely need to rename a job, update the branch protection rules in the same PR.