Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (78 loc) · 3.53 KB

CONTRIBUTING.md

File metadata and controls

109 lines (78 loc) · 3.53 KB
Raw

Contributing

Thanks for your interest in improving Buscar. Contributions that fix bugs, improve documentation, add tests, or make the package easier to install and maintain are welcome.

Development Setup

Buscar uses uv for environment and package management.

git clone https://github.com/WayScience/buscar.git
cd buscar
uv sync --frozen --group dev

Install the pre-commit hooks before making changes:

uv tool install pre-commit
pre-commit install

Checks

Run the test suite:

uv run --frozen pytest

Run tests with coverage:

uv run --frozen pytest --cov=buscar --cov-report=term-missing --cov-report=xml --cov-report=html

The coverage run creates coverage.xml and an htmlcov/ directory. CI uploads these files from the Ubuntu Python 3.12 test job so maintainers can download the machine-readable coverage report or inspect the browsable HTML coverage report when reviewing pull requests.

Run linting and formatting checks:

pre-commit run --all-files

Build the package:

uv build
uv run --frozen twine check dist/*

Pull Requests

Before opening a pull request:

  • Keep changes focused on one bug fix, feature, or documentation update.
  • Add or update tests when behavior changes.
  • Update documentation when user-facing behavior changes.
  • Run uv run --frozen pytest and pre-commit run --all-files.
  • Make sure generated files and large local artifacts are not committed.

CI runs pre-commit checks, the test matrix across supported Python versions, and package build validation.

Dependabot checks GitHub Actions and pre-commit hooks weekly, and uv-managed Python dependencies monthly. Review dependency update pull requests like any other change and make sure CI passes before merging.

Releases

A push to main runs .github/workflows/draft-release.yml. Release Drafter updates a draft GitHub release with merged pull requests. Use the release-major, release-minor, or release-patch label to choose the version bump; the default is a patch bump.

Before the first release, a maintainer must:

  1. Create the release environment in the WayScience/buscar GitHub repository. Add required reviewers if the release needs approval.
  2. Create the release-major, release-minor, and release-patch labels if they do not exist. Apply them to pull requests that need a specific version bump.
  3. In their PyPI account's Publishing settings, add a pending trusted publisher for the buscar project. Set the owner to WayScience, repository to buscar, workflow filename to publish-pypi.yml, and environment to release. The pending publisher does not reserve the project name until the first upload.

To release, make sure CI passes on main. Review the draft release and its vX.Y.Z tag, then publish it from GitHub Releases. Publishing the GitHub release runs .github/workflows/publish-pypi.yml. That workflow builds a wheel and source distribution from the release tag, checks the wheel import, and uploads both files to PyPI with Trusted Publishing. No PyPI API token is needed. Check the new version on PyPI after the workflow finishes.

Reporting Issues

When reporting a bug, include:

  • The Buscar version or commit you are using.
  • Your Python version and operating system.
  • A minimal example or traceback that reproduces the issue.
  • Any relevant input data shape, schema, or metadata column names.

License

By contributing, you agree that your contribution will be licensed under the BSD 3-Clause license used by this project.