diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6e1c8a57b8..9b2c2bf107 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -314,3 +314,41 @@ python -m pip install --upgrade awkward python -m pip uninstall --yes awkward awkward-cpp python -m pip install --upgrade --extra-index-url https://pypi.anaconda.org/scientific-python-nightly-wheels/simple awkward ``` + +### Guidelines for Dependency and Version Changes + +To ensure stability and reproducibility across the Awkward ecosystem: + +1. Collaborative Review Required + - Pull requests that affect core dependencies (e.g., Numba, Pandas, PyArrow, NumPy) or Python version support must be discussed with maintainers before merging. + - This avoids unilateral decisions that could break critical workflows. + +2. Compatibility Transparency + - If a dependency is not yet available for a new Python release, note this clearly in the PR description and documentation. + - Example: “Supports Python 3.14, but Numba-dependent features are disabled until upstream support is released.” + +3. Testing Expectations + - CI should run against all supported Python versions. + - Tests that depend on unsupported features (e.g., Numba on Python 3.14) must be marked with xfail so contributors see the limitation. + +4. Version Pinning + - Pin or constrain versions of critical dependencies to prevent silent breakages from upstream changes. + - Floating versions may be allowed for secondary utilities, but core scientific packages should be locked. + +5. Communication + - Use GitHub Discussions or Issues to propose changes before opening a PR that alters compatibility. + - This ensures consensus and avoids surprises for downstream users. + + + +--- + +#### Example PR Checklist + +- Have I discussed this change with maintainers? + +- Did I document limitations (e.g., missing Numba support)? + +- Are CI tests updated to reflect compatibility status? + +- Did I pin or constrain critical dependencies?