Contributing & Development Standards

Contribution workflow

1. Fork or branch from the current production baseline.
2. Make a focused change.
3. Add or update tests for changed behavior.
4. Run the affected model suite.
5. Validate imports from the installed package namespace (cooprecsys), not only from the source path.
6. For Cython changes, rebuild the native extensions and test runtime backend selection.
7. Update the corresponding docs page when behavior or interfaces change.
8. Open a pull request with the technical rationale and regression surface.

Native code changes

For ary2tower/CLtowers changes, test at least:

python ./src/cooprecsys/models/ary2tower/a2tcysetup.py build_ext --inplace

Then run an actual forward/training/inference call. Compilation success is not enough; the runtime must load the intended extension modules.

API compatibility

Preserve the distinction between repository paths and package imports:

from cooprecsys.models.ary2tower import TwoTowerInference

not:

from src.models.ary2tower import TwoTowerInference

Regression coverage for recommendation count

Ary2Tower changes should explicitly test the top-N contract. A request for N must return N unique eligible items whenever the catalogue makes that mathematically possible. Purchase exclusion must not silently reduce the result count.

The residual fallback is part of that contract and should be tested for both presence and source attribution.