Skip to content

CONTRIBUTING.md

This guide outlines the workflow and standards for developers looking to extend or maintain the OpenSportsLib library.

AI Agent Contributions

For AI-agent driven development, follow AGENTS.md in the repository root.

1. Development Environment Setup

To begin contributing, set up a local development environment in "editable" mode so your changes are immediately reflected in the package.

Step 1: Clone the Repository

git clone https://github.com/OpenSportsLab/opensportslib.git 
cd opensportslib

Step 2: Create a Virtual Environment

Use Conda to manage dependencies and ensure Python 3.12 compatibility. 

conda create -n osl python=3.12 pip
conda activate osl

Step 3: Install in Editable Mode

Install the base package or include optional dependencies for specific tasks like localization: 

# Install core package in editable mode
pip install -e .

Step 4: Setup Environment (PyTorch, CUDA aware & Optional Dependencies)

# Install PyTorch (CPU/GPU auto-detected)
opensportslib setup

# Optional: install PyTorch Geometric support
opensportslib setup --pyg

# Optional: install for DALI support
opensportslib setup --dali

# Optional: install the X-VARS-compatible VQA dependency profile
opensportslib setup --vqa_xvars

# Optional: install the Qwen-compatible VQA dependency profile
opensportslib setup --vqa_qwen

2. Branching and Merging - Daily workflow for developers

Branches

main → stable, production-ready dev → active development integration branch dev- → developer personal branch feature- → new features fix- → bug fixes

Rules

  • ❌ Never push directly to main
  • ❌ Never commit directly to dev
  • ✅ Always create a feature branch from dev
  • ✅ Always use Pull Requests
  • ✅ PRs must target dev, NOT main

1. Sync Repo

Verify your current branch is dev and pull the latest changes before starting work. 

git checkout dev
git pull origin dev

2. Create Feature Branch

Create a new branch from the dev source using descriptive naming conventions. 

git checkout -b feature-<feature_name>
Naming Examples: - feature-model - feature-new-dataset

3. Work Locally

Commit your work often using the following commit style guidelines:

  • feat: New feature
  • fix: Bug fix
  • refactor: Code cleanup
  • docs: Documentation update

Example commit: 

git add . 
or 
git add -u

git commit -m "feat: add model registry"

4. Push Branch (just once)

Push your feature branch to the remote repository. 

git push origin feature/your-feature-name

5. Open Pull Request (PR) → dev

Raise a Pull Request (PR) to merge your branch back into the dev branch.

Package versions are managed by GitHub Actions. Do not change the root pyproject.toml package version or the OpenSportsLib dependency pin in server/pyproject.toml in a PR to dev; the required Version Integrity check will reject those edits. Maintainers should follow the release-management guide for feature release-line preparation and stable releases.

Every GitHub-linked commit author must accept the Individual CLA when prompted by the CLA check. Post the exact signing phrase configured in .github/cla.yml; see .github/CLA.md for the agreement. Run the supported test entry point before opening the PR:

bash scripts/run_tests.sh

✅ PR Checklist: - [ ] Tests Pass: All existing logic remains functional. - [ ] Runs on GPU: Code is compatible with CUDA environments. - [ ] Config Works: YAML configurations resolve correctly. - [ ] Docs Updated: Relevant documentation reflects your changes.