Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
120 lines (89 loc) · 4.64 KB

CONTRIBUTING.md

File metadata and controls

120 lines (89 loc) · 4.64 KB
Raw

Contributing to BenchCore

Thank you for considering a contribution. BenchCore is being designed as a long-lived public library, so clarity of behavior and API stability matter more than adding features quickly.

Before you begin

Please read the README to understand the project's scope, GOVERNANCE.md for decision making, and the Code of Conduct before participating.

For a typo, documentation correction, or other narrowly scoped fix, a pull request is usually enough. For new public APIs, architectural changes, dependencies, integrations, or substantial behavior changes, open an issue first. The discussion should establish the problem before choosing an implementation.

Security vulnerabilities must be reported privately according to SECURITY.md.

Design process

Substantial proposals should proceed in this order:

  1. Describe the user problem and concrete use cases.
  2. Compare plausible designs and their trade-offs.
  3. Define the public interfaces and observable behavior.
  4. Define types and data models.
  5. Agree on compatibility and performance implications.
  6. Implement the smallest design that solves the accepted problem.

Every proposed class, protocol, module, dependency, or design pattern should solve a current problem. Explain why a simpler solution is insufficient and how the proposal affects extensibility, maintainability, typing, and measurement overhead.

Architecture principles

Contributions are expected to preserve these constraints:

  • The benchmarking engine remains independent of testing frameworks.
  • Framework-specific code stays in isolated integration modules.
  • Runtime dependencies remain as close to zero as practical.
  • Public APIs are fully typed and never expose Any.
  • Callable signatures and return types are preserved where relevant.
  • Composition is preferred over inheritance.
  • Data is immutable when mutation is unnecessary.
  • Benchmarking overhead and hidden side effects are minimized.
  • New abstractions are introduced only for demonstrated use cases.

BenchCore targets Python 3.12 and newer. Code should be compatible with Pyright strict mode and use modern Python features when they improve clarity.

Development setup

BenchCore targets Python 3.12 and newer. You also need Git and Poetry. Clone the repository and install the environment with:

git clone https://github.com/ezer-mackenzie/benchcore.git
cd benchcore
poetry install

Before submitting code, run the same quality checks enforced by CI:

poetry run ruff format --check src tests examples
poetry run ruff check src tests examples
poetry run pyright
poetry run pytest -p no:benchcore --cov=benchcore --cov-report=term-missing --cov-fail-under=100
poetry run mkdocs build --strict
poetry build

CI runs the test suite on every supported Python version. A contributor normally needs only one supported interpreter locally; the matrix provides the remaining compatibility check.

Tests and benchmarks

  • Add tests for new behavior and regressions for bug fixes.
  • Test public behavior rather than private implementation details.
  • Keep tests deterministic and independent of machine speed where possible.
  • Do not use a timing threshold as the sole correctness assertion.
  • Include performance evidence when a change claims lower overhead or greater accuracy, and describe the environment and methodology.

The core test suite may use pytest as a development tool. This does not permit a runtime dependency on pytest in the benchmarking engine.

Documentation and changelog

Document public APIs, important semantics, limitations, and design decisions. Examples must distinguish implemented behavior from proposed behavior.

Add a concise entry under Unreleased in CHANGELOG.md for a user-visible change. Purely internal refactors and minor typo fixes generally do not need an entry.

Changes to package-level public exports must also follow COMPATIBILITY.md and update the API snapshot tests.

Pull requests

Keep each pull request focused. Its description should explain:

  • the problem being solved;
  • the chosen design and alternatives considered;
  • effects on the public API, typing, compatibility, and performance;
  • how the change was verified;
  • any follow-up work intentionally left out of scope.

Avoid unrelated formatting or refactoring. Maintainers may request that a large proposal be split into smaller reviewable changes. A contribution can be declined when it conflicts with the project's scope or maintenance goals, even if the implementation works.

By contributing, you agree that your contribution will be distributed under the project's license.