Thank you for your interest in contributing to python-uv! This document describes how to propose changes. Development details live in the documentation, which this page links to.
All contributors must follow our Code of Conduct.
- Set up your development environment: Getting Started
- Create a branch from
main: Branch Strategy & Release Flow - Make changes following the Code Standards
- Run the quality checks: Before Submitting
- Submit a pull request to
mainusing our template
git checkout -b feature/your-feature-nameUse a prefix from Branches (feature/, fix/, hotfix/, refactor/). What happens after your PR is merged into main is described in Branch Strategy & Release Flow.
- Write clear, focused commits - Each commit should represent a single logical change
- Follow the Code Standards - including type hints, docstrings, and tests
- Update documentation - Edit the page under
docs/that owns the topic (see Documentation)
Use descriptive commit messages:
# Good commit messages
git commit -m "add: CloudWatch logging support"
git commit -m "fix: Handle None values in Logger.format()"
git commit -m "update: Improve type hints in Settings class"
git commit -m "refactor: Simplify Timer context manager logic"
git commit -m "test: Add edge cases for config loading"
git commit -m "docs: Update contributing guidelines"
# Avoid
git commit -m "updates"
git commit -m "fix bug"
git commit -m "changes"You MUST pass all quality checks before submitting your PR. The commands and their flags are listed in Task Automation with nox:
- Code is formatted:
uv run nox -s fmt -- --ruff --sqruff - Linting passes:
uv run nox -s lint -- --ruff --sqruff --ty - All tests pass:
uv run nox -s test(coverage ≥ 75%) - Pre-commit hooks pass:
uv run pre-commit run --all-files - New test files follow the
test__*.pynaming convention - Dependencies are added via
uv add, anduv.lockis committed - Documentation is updated under
docs/ - Breaking changes are documented (if applicable)
PRs with failing checks will not be reviewed. If a check fails, see Common Issues.
-
Push your branch to your fork:
git push origin feature/your-feature-name
-
Create a Pull Request against
mainon GitHub- The PR template will be auto-populated
- Fill out all sections completely
- Link related issues using
Fixes #123orRelates to #456
-
PR Template Sections to Complete:
- Summary - What and why you made these changes
- Type of Change - Select applicable change types
- Related Issues - Link to issues
- Changes Made - List main changes
- Testing - Confirm all test commands passed
- Pre-Submission Checklist - Verify all items
- Breaking Changes - Document if applicable
- Additional Notes - Screenshots, performance notes, etc.
- Automated checks run on your PR (see CI/CD Workflows)
- Maintainers review your code using the review checklist
- Address feedback if changes are requested
- PR is merged once approved
Review Timeline:
- Initial review: Within 2-3 business days
- Follow-up reviews: Within 1-2 business days
- Documentation: https://a5chin.github.io/python-uv (source:
docs/) - PR Template: .github/PULL_REQUEST_TEMPLATE.md
- GitHub Issues: For bug reports and feature requests
- GitHub Discussions: For questions and general discussions
- Pull Request Comments: For questions about specific code changes
Thank you for contributing to python-uv! 🎉