Contributing to scXpand

Contributing to scXpand#

We welcome contributions to scXpand! This document provides guidelines for contributing to the project.

Reporting Issues#

When reporting issues, please include:

  • Python version

  • scXpand version

  • Operating system

  • Minimal reproducible example

  • Expected vs actual behavior

Contributing Process#

Quick Start:

  1. Fork and clone the repository

  2. Set up development environment: Follow the “Development Setup (from Source)” instructions in Installation Guide

  3. Create a feature branch and make your changes

Before submitting your pull request:

  1. Ensure all tests pass and meet coverage requirements:

    # Install in editable mode and run tests with coverage
pytest --cov=scxpand -n auto

  2. Add tests for new functionality

  3. Update documentation if your changes affect the API or user-facing functionality

  4. Run pre-commit hooks to ensure code quality:

    # Run linting and formatting
pre-commit run --all-files

Submit your pull request:

  1. Create a pull request with:

    • Clear, descriptive title

    • Detailed description of changes

    • Reference to any related issues

    • Screenshots or examples if applicable

  2. Request review from maintainers

Your pull request will be reviewed and may require changes before being merged.

Template Updates#

This project uses the scverse cookiecutter template and can be updated when new template versions are released.

To update the project with the latest template changes:

# Check if updates are available
cruft check

# Update to the latest template version
cruft update

# Review and commit the changes
git add .
git commit -m "Update from cookiecutter template"

Testing#

The project uses pytest with coverage reporting and parallel execution. After following the development setup in Installation Guide. Tests also run automatically via pre-commit hooks before push, but you can run them manually with the following commands:

 # Install in editable mode and run all tests with coverage (recommended)
pytest --cov=scxpand -n auto

 # Run tests without parallel execution (if you encounter issues)
 pytest --cov=scxpand

 # Run specific test files
 pytest tests/data_util/test_data_format.py

 # Generate HTML coverage report
 pytest --cov=scxpand --cov-report=html -n auto

Test Coverage:

The project maintains a minimum test coverage of 80%. Coverage reports are generated in: - Terminal output with missing lines - HTML report in the htmlcov/ directory - XML report for CI/CD integration

Note: The -n auto flag automatically detects the optimal number of parallel workers.

Release Process#

For Maintainers Only

We use GitHub Actions for automated dual package releases (standard and CUDA versions). The release process is fully integrated with CI/CD and includes tests.

Creating Releases#

Method 1: GitHub Actions UI (Recommended)

  1. Go to the Actions tab in GitHub

  2. Click “Run workflow”

  3. Select the version bump type (patch/minor/major)

  4. Optionally check “Create dev release” for testing

  5. Click “Run workflow”

Method 2: Manual Tag Push

# Create and push a version tag
git tag v0.4.6
git push origin v0.4.6

Release Types#

Regular Releases: - Create GitHub releases with auto-generated notes - Publish both scxpand (CPU/MPS) and scxpand-cuda (CUDA) packages - Trigger ReadTheDocs documentation builds

Dev Releases: - No GitHub release creation - Publish packages with .dev0 suffix (e.g., 0.4.6.dev0) - Useful for testing before official releases

Version Management#

We use Semantic Versioning with VCS-based versioning:

  • MAJOR: Incompatible API changes (1.0.0 → 2.0.0)

  • MINOR: Backward-compatible functionality additions (1.0.0 → 1.1.0)

  • PATCH: Backward-compatible bug fixes (1.0.0 → 1.0.1)

  • Version source: Git tags (e.g., v0.4.6, v0.4.7.dev0)

  • No manual version bumping required in pyproject.toml

Documentation#

Build docs locally:

cd docs && python build_docs.py --serve
Contents