Skip to content

PUBLISHING.md

Latest commit

 

History

History
228 lines (152 loc) · 4.3 KB

PUBLISHING.md

File metadata and controls

228 lines (152 loc) · 4.3 KB

Publishing Guide

This document describes the process for building, testing, and publishing RepoDoctor to PyPI.

Prerequisites

  • uv package manager installed
  • PyPI account with API token
  • Write access to the repository

Version Management

RepoDoctor follows Semantic Versioning:

  • MAJOR version: Incompatible API changes
  • MINOR version: New functionality (backward-compatible)
  • PATCH version: Bug fixes (backward-compatible)

Version Locations

Update the version in the following files:

  1. pyproject.toml - [project] version = "x.y.z"
  2. src/repodoc/__init__.py - __version__ = "x.y.z"
  3. CHANGELOG.md - Add new version entry

Pre-Release Checklist

Before publishing a new release:

  • All tests pass: uv run pytest
  • No linting errors: uv run ruff check
  • Code is formatted: uv run ruff format --check
  • No type errors: uv run ty check
  • Version bumped in all files
  • CHANGELOG.md updated with changes
  • README.md is up-to-date
  • Git working directory is clean

Building the Package

1. Clean Previous Builds

# Remove old distribution files
rm -rf dist/

2. Build Distribution Packages

# Build both wheel and source distribution
uv build

This creates:

  • dist/repodoc-{version}-py3-none-any.whl - Wheel package
  • dist/repodoc-{version}.tar.gz - Source distribution

3. Verify Package Contents

# List contents of the wheel
python -m zipfile -l dist/repodoc-{version}-py3-none-any.whl

# Check package metadata
uv pip show repodoc

4. Test Local Installation

# Install from wheel
uv pip install dist/repodoc-{version}-py3-none-any.whl

# Verify CLI works
repodoc --version
repodoc --help

# Run a test command
repodoc diet --help

# Uninstall after testing
uv pip uninstall repodoc

Publishing to PyPI

Test PyPI (Recommended First)

  1. Configure Test PyPI credentials:
# Create/edit ~/.pypirc
[testpypi]
username = __token__
password = pypi-YOUR-TEST-PYPI-TOKEN
  1. Upload to Test PyPI:
uv publish --repository testpypi dist/*
  1. Test installation from Test PyPI:
uv pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ repodoc

Production PyPI

  1. Configure PyPI credentials:
# Create/edit ~/.pypirc
[pypi]
username = __token__
password = pypi-YOUR-PYPI-TOKEN
  1. Upload to PyPI:
uv publish dist/*
  1. Verify on PyPI:
  1. Test installation:
uv pip install repodoc
repodoc --version

Creating a GitHub Release

After publishing to PyPI:

  1. Tag the release:
git tag -a v{version} -m "Release version {version}"
git push origin v{version}
  1. Create GitHub Release:
  1. Update CHANGELOG.md:
## [Unreleased]

## [{version}] - {date}

### Added

- Feature 1
- Feature 2

### Changed

- Change 1

### Fixed

- Bug fix 1

Rollback Procedure

If you need to yank a release from PyPI:

# Yank a specific version (keeps it available but marks it as yanked)
uv publish --yank {version}

Note: You cannot delete a version from PyPI, only yank it.

Automation (Future)

Consider setting up GitHub Actions for:

  • Automated testing on PRs
  • Automated building on tags
  • Automated publishing to PyPI on release

Troubleshooting

Build Fails

  • Check that all source files are included
  • Verify pyproject.toml is valid
  • Run uv build --verbose for detailed output

Upload Fails

  • Verify PyPI token is correct and has upload permissions
  • Check that version doesn't already exist on PyPI
  • Ensure package name is available (first-time publish)

Installation Fails

  • Check Python version compatibility (>=3.11)
  • Verify all dependencies are available on PyPI
  • Check for platform-specific issues

Support

For issues with publishing: