Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
114 lines (78 loc) · 3.13 KB

CONTRIBUTING.md

File metadata and controls

114 lines (78 loc) · 3.13 KB
Raw

Development

API Documentation

References for developing new features:

Local Development

This package uses mise (installation guide) for dependency management, prek for fast pre-commit hooks, uv as the build engine, and tox for test automation.

To install the development dependencies:

brew install mise  # or see the installation alternatives above

# Install dependencies from mise.toml
mise trust
mise install

# Configure prek
prek install -f

To run all tox environments:

tox

or to run specific commands:

tox -e test
tox -e prek
tox -e hook-min

tox list

To run all pre-commit steps:

prek run --all

pytest-watcher ([tool.pytest-watcher] in pyproject.toml) reruns tests on file changes

ptw .

Local uv/pipx integration testing

Run the local code with uv tool (requires uv installed globally and first in $PATH, e.g. brew install uv or mise use uv --global)

uv tool install --force --with=. 'mdformat>=0.7.19'

# Then navigate to a different directory and check that the editable version was installed
cd ~
mdformat --version
which mdformat

Or with pipx:

pipx install . --include-deps --force --editable

Publish to PyPI

This project publishes from GitHub Actions with PyPI Trusted Publishers (no API tokens) and builds with uv.

Initial Setup (One-time)

Before publishing for the first time, configure Trusted Publishing on PyPI:

  1. Go to your project's page on PyPI: https://pypi.org/manage/project/mdformat_mkdocs/settings/publishing/
  2. Add a new Trusted Publisher with these settings:
    • PyPI Project Name: mdformat_mkdocs
    • Owner: kyleking
    • Repository name: mdformat-mkdocs
    • Workflow name: tests.yml (.github/workflows/tests.yml)
    • Environment name: pypi
  3. Configure the GitHub Environment:
    • Go to your repository's Settings → Environments
    • Create an environment named pypi
    • (Recommended) Enable "Required reviewers"

Publishing a Release

Use commitizen to bump versions (in pyproject.toml and mdformat_mkdocs/__init__.py) and create a tagged commit:

# Dry run to preview the version bump
tox -e cz -- --dry-run

# Automatically bump version based on conventional commits
tox -e cz

# Or manually specify the increment type
tox -e cz -- --increment PATCH  # or MINOR or MAJOR

# Push the commit and tag
git push origin main --tags

The GitHub Action then builds and publishes to PyPI.