Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
149 lines (110 loc) · 4.82 KB

CONTRIBUTING.md

File metadata and controls

149 lines (110 loc) · 4.82 KB

Contributing to pyCosign

First off, thank you for taking the time to contribute!
The following guidelines help keep the project consistent and maintainable.

Table of Contents

  1. Code of Conduct
  2. Getting Started
  3. Branching & Workflow
  4. Commit Conventions
  5. Developer Certificate of Origin (DCO)
  6. Coding Style
  7. Testing
  8. Pull-Request Checklist
  9. Release Process

Code of Conduct

We follow the Contributor Covenant v2.1.
Please be respectful and inclusive in all interactions.

Getting Started (Poetry)

# clone
git clone https://github.com/your-org/pycosign.git
cd pycosign

# install Poetry (if not already)
curl -sSL https://install.python-poetry.org | python3 -

# create & activate venv + install deps
poetry install --with dev

# drop into project shell
poetry shell

# install git hooks
pre-commit install

*Poetry automatically selects Python ≥ 3.10 on your system or the one specified in pyproject.toml. All dev tools—ruff, black, mypy, pytest, invoke—are declared under [tool.poetry.group.dev].*  

### Prerequisites

| Tool             | Required Version | Notes |
|------------------|------------------|-------|
| **Poetry**       | 1.8 or newer     | Dependency & virtual-env manager |
| **Python**       | 3.10 – 3.12      | Poetry will auto-select within this range |
| **cosign CLI**   | ≥ 2.2            | `brew install sigstore/tap/cosign` or download release binary |
| **plantuml**     | _optional_       | Render `.puml` diagrams locally (`brew install plantuml`) |
| **Docker**       | _optional_       | Quick PlantUML preview, OCI registry tests |

## Branching & Workflow

* **`main`** — always releasable; tagged releases are cut from here.  
* **Feature branches** — name `feature/<short-topic>` (e.g., `feature/registry-push`).  
* **Bug-fix branches** — name `bugfix/<issue-#>` (e.g., `bugfix/42-null-sig-path`).  
* **Documentation-only branches** — name `docs/<topic>`.

Workflow:

1. Create an **Issue** if one doesn’t exist.  
2. Branch from `main` with the naming rules above.  
3. Work locally in a Poetry shell:  
   ```bash
   poetry shell
   git checkout -b feature/my-cool-thing
  1. Keep commits small, descriptive, and signed (git commit -s).
  2. Push to your fork / to the repo: git push -u origin feature/my-cool-thing.
  3. Open a pull request against main. GitHub Actions will run:
  • lint → test → type-check → coverage → packaging checks.
  1. Address review comments; squash-merge once approved.

Tip: Use git rebase -i main to keep history clean before opening the PR.

Commit Conventions

We follow Conventional Commits:

feature(signer): add --push flag for sign-blob
bugfix(verifier): handle missing Rekor bundle gracefully
docs: update README diagrams

Developer Certificate of Origin (DCO)

By submitting a PR you certify you have the right to submit the work under the project’s MIT license. Sign your commits:

git commit -s -m "bugfix: correct typo"

The -s flag adds the required Signed-off-by line.

Coding Style

  • ruff for linting (black, isort, flake8 rules)
  • Docstrings follow Google style.

Run all checks:

  • black for formatting (PEP 8 compliant).
poetry run black --verbose pycosign
  • isort your imports, so you don't have to.
poetry run isort --verbose pycosign

Testing

  • pytest with pytest-asyncio for async routines.
  • 90%+ coverage target.
pytest -q

CI will fail if coverage drops below the threshold.

Pull-Request Checklist

Before requesting a review, make sure you can check every box below:

  • Issue linked (e.g., “Closes #123”) or marked N/A for trivial docs fixes.
  • Unit / integration tests added or updated; poetry run pytest passes locally.
  • Docs updated (README, docs/, or inline docstrings) if behavior changed.
  • Changelog entry added under ## [Unreleased] in CHANGELOG.md.
  • pre-commit run --all-files passes (ruff, black, mypy, etc.).
  • All commits are signed (git commit -s) to satisfy the DCO.
  • PR title follows Conventional Commits (e.g., feat(verifier): add policy flag).
  • CI status is green (GitHub Actions).

🔒 PRs without a Signed-off-by line will be blocked by the DCO GitHub check.

Release Process

  1. Merge all features into main.
  2. Bump version with bumpver update --push-tag.
  3. GitHub Action builds sdist & wheels and uploads to PyPI.
  4. Draft release notes in CHANGELOG.md.

Happy hacking! 💙