Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
88 lines (65 loc) · 3.95 KB

CONTRIBUTING.md

File metadata and controls

88 lines (65 loc) · 3.95 KB
Raw

Contributing

Thanks for looking. This library is small, dependency-free and deliberately strict about exactness — please keep it that way.

Getting set up

python -m venv .venv && . .venv/bin/activate
pip install -e . pytest
pytest

The suite should be green before you change anything, so that any later failure is yours.

The rules that matter here

No floats in geometry or feasibility. Every length is an integer number of ticks (1/16000 mm) and every weight an integer number of 1/8 µg. If a change makes a placement decision depend on binary floating point, it is wrong even if the tests pass — see docs/UNITS-AND-NUMERICS.md. Ratios are compared as scaled integers or exact rationals.

No runtime dependencies. The package installs with nothing else. A new dependency needs a very good argument.

Inputs are immutable. A pack call must never mutate the items or containers it was given. This is a correctness property people rely on when reusing request objects.

Determinism. The same input and seed must produce the same output. Avoid iteration over unordered collections where the order can reach a result; sort explicitly.

Every fixed defect gets a regression test. Not "a test somewhere" — a test that fails before your fix and passes after.

Behavioural changes

This package is one of three independent implementations of the same documented contract; the PHP and Rust ports must produce identical placements for the same request. That means:

  • A change to solver behaviour, the objective vector, serialization field names or status semantics is a cross-language change. Open an issue describing it before writing code, so the other implementations move with it.
  • A change confined to Python internals — typing, refactoring, performance without a change in output — is local and needs no coordination.

If you are unsure which kind you have, run your change against the examples and see whether any placement moves.

Pull requests

  • One logical change per pull request.
  • Commit messages in imperative mood, under 72 characters: type(scope): description with feat, fix, refactor, chore, docs or test.
  • Add or update tests. pytest must pass on Python 3.10 through 3.13.
  • Update the relevant document under docs/ when you change behaviour. Complexity, limitations and failure modes are part of the change, not follow-up work.
  • Do not bump the version; releases are cut separately.

Reporting a bug

Please include the full request that reproduces it — items, containers and configuration — and what you expected instead. A packing bug is nearly impossible to act on without the exact input.

For anything with security implications, follow SECURITY.md rather than opening a public issue.

How your feedback is handled

Every issue and discussion is read by a maintainer. This is what happens next:

  1. New issues are labelled needs-triage. A maintainer answers with one of: a question back to you, a confirmation, or a reason it will not be taken on.
  2. A confirmed bug gets the bug label and is reproduced from your request. A wrong result in one package is checked against the others, because all of them implement the same contract and must agree.
  3. An accepted feature request or idea is added to the project's backlog, and the issue is labelled accepted with a comment saying so. An idea from Discussions is first turned into an issue and linked back to the discussion.
  4. When the change ships, the issue is closed with the release it shipped in. A change to the request or result format can only ship in a release that is allowed to change it, so it may take more than one release.
  5. Declined requests are closed with the reason, so you are never left waiting on a silent issue.

Questions go to Discussions → Q&A; security problems go to Report a vulnerability under the Security tab, never to a public issue.