Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
114 lines (78 loc) · 3.32 KB

CONTRIBUTING.md

File metadata and controls

114 lines (78 loc) · 3.32 KB

Development

API Documentation

A collection of useful resources to reference when developing new features:

Local Development

This package utilizes 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 mist.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 is configured in pyproject.toml for [tool.pytest-watcher] to continuously run tests

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 'mdformat>=0.7.19' --force --with=.

# 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 uses PyPI Trusted Publishers for secure, token-free publishing from GitHub Actions, with uv for building packages.

Initial Setup (One-time)

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

  1. Go to your project's page on PyPI: https://pypi.org/manage/project/mdformat_obsidian/settings/publishing/
  2. Add a new Trusted Publisher with these settings:
    • PyPI Project Name: mdformat_obsidian
    • Owner: kyleking
    • Repository name: mdformat-obsidian
    • 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" for production safety

Publishing a Release

Use commitizen to automatically bump versions (in pyproject.toml and mdformat_obsidian/__init__.py) and create a commit with tag:

# 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 will automatically build and publish to PyPI using Trusted Publishers (no API tokens needed!).