Contributing to LongProbe¶
Thank you for your interest in contributing to LongProbe! This guide will help you get started.
Development Setup¶
1. Fork and Clone¶
# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/LongProbe.git
cd LongProbe
2. Install Dependencies¶
3. Run Tests¶
# Run unit tests
uv run pytest tests/unit/ -v
# Run all tests including integration
uv run pytest tests/ -v --run-integration
# Run with coverage
uv run pytest --cov=longprobe --cov-report=html
4. Lint and Format¶
# Check code style
uv run ruff check src/
# Auto-fix issues
uv run ruff check --fix src/
# Format code
uv run ruff format src/
Making Changes¶
1. Create a Branch¶
2. Make Your Changes¶
- Write clear, concise code
- Add tests for new features
- Update documentation as needed
- Follow existing code style
3. Test Your Changes¶
# Run tests
uv run pytest tests/
# Check linting
uv run ruff check src/
# Format code
uv run ruff format src/
4. Commit Your Changes¶
Use conventional commit messages:
- feat: - New feature
- fix: - Bug fix
- docs: - Documentation changes
- test: - Test changes
- refactor: - Code refactoring
- chore: - Maintenance tasks
5. Push and Create PR¶
Then create a Pull Request on GitHub.
Code Style¶
We use Ruff for linting and formatting:
Testing Guidelines¶
Writing Tests¶
# tests/unit/test_feature.py
import pytest
from longprobe import LongProbe
def test_feature():
"""Test description."""
# Arrange
probe = LongProbe(...)
# Act
result = probe.some_method()
# Assert
assert result == expected
Running Specific Tests¶
# Run specific test file
uv run pytest tests/unit/test_scorer.py -v
# Run specific test
uv run pytest tests/unit/test_scorer.py::test_recall_calculation -v
# Run with markers
uv run pytest -m "not slow" -v
Documentation¶
Building Docs Locally¶
# Install docs dependencies
pip install mkdocs-material mkdocstrings[python]
# Serve docs locally
mkdocs serve
# Build docs
mkdocs build
Writing Documentation¶
- Use clear, simple language
- Include code examples
- Add links to related pages
- Test all code examples
Pull Request Process¶
- Update Documentation - If you add features, update docs
- Add Tests - New features need tests
- Pass CI - All tests must pass
- Code Review - Address reviewer feedback
- Squash Commits - Clean up commit history if needed
Release Process¶
(For maintainers)
- Update
CHANGELOG.md, set the version inpyproject.toml, and regenerate any changed demo GIFs. - Commit the source changes and updated
assets/*.giffiles. The checkout README uses public GIF links from the configured repository’smainbranch. Push changed assets there so previews show the latest published recordings. - Push the release commit and matching
v<version>tag to the public image repository configured in[tool.hatch.metadata.hooks.custom]. It currently points toAbdullahbinmushtaq/LongProbe; changeimage-base-urlif another repository will host release images. - Build with
uv build. The metadata hook pins public or local GIF links to public URLs under the matching version tag in the wheel and source-distribution descriptions. It does not editREADME.mdor upload images. - Run
uv run python examples/verify_pypi_readme.pyto check both distribution descriptions and confirm that package builds preserve the checkout README. - Run
uv run python examples/verify_pypi_readme.py --check-publicbefore uploading to PyPI. This downloads the tagged public images and checks that they match your local release assets. The tag workflow runs this check before creating its GitHub release. A version change or PyPI upload alone does not publish GitHub assets. The existing tag workflow builds the package and creates a GitHub release; it does not upload to PyPI.
For example, package version 0.2.0 produces image URLs such as:
https://raw.githubusercontent.com/Abdullahbinmushtaq/LongProbe/v0.2.0/assets/01-complete-workflow.gif
Each release uses its own tagged assets, so later GIF changes on main do not change older PyPI descriptions. After changing the package version, build new distributions; uploading an older wheel will retain its older description.
Getting Help¶
- GitHub Issues: Report bugs or request features
- Discussions: Ask questions
Code of Conduct¶
Be respectful and inclusive. We're all here to build great tools together.
License¶
By contributing, you agree that your contributions will be licensed under the MIT License.