Skip to content

MAINTAINERS.md

Latest commit

 

History

History
273 lines (185 loc) · 7.27 KB

MAINTAINERS.md

File metadata and controls

273 lines (185 loc) · 7.27 KB
Raw

Maintainers Guide

Instructions for releasing and maintaining the parallel-web-tools package.

Development Setup

From the repository root:

Install Option 1: Nix

Create a .envrc file in the repo root containing:

use flake;

Install Option 2: Manual

Make sure you have the following installed:

  • uv
  • Python 3.12
  • Node 24
  • pnpm

First time setup

Sets up Python, installs all dev dependencies, and sets up pre-commit:

uv sync --extra dev

# Install git hooks
uv run pre-commit install

# Run hooks manually on all files
uv run pre-commit run --all-files

Running development version of parallel-cli

Just run:

uv run parallel-cli

If you want to build the binary for whatever reason:

uv run python scripts/build.py

Release Process

Quick Release (Recommended)

From the main branch with a clean working tree:

# Release candidate (most common)
./scripts/release.sh rc

# Promote RC to stable
./scripts/release.sh stable

# Explicit version
./scripts/release.sh 0.2.0

This script will:

  1. Calculate the next version
  2. Update all 4 version files
  3. Create a release/vX.Y.Z branch
  4. Commit, push, and open a PR

After you merge the PR, everything else is automated:

  • auto-release.yml detects the version bump commit and creates a GitHub Release + tag
  • release.yml builds standalone binaries for all platforms
  • publish.yml publishes to PyPI
  • npm publish is handled by the release workflow

Manual Version Update (if needed)

Update the version in these places:

  • pyproject.toml: version = "X.Y.Z"
  • parallel_web_tools/__init__.py: __version__ = "X.Y.Z"
  • parallel_web_tools/integrations/bigquery/cloud_function/requirements.txt: parallel-web-tools>=X.Y.Z
  • npm/package.json: "version": "X.Y.Z" (use semver pre-release format for RCs, e.g. "X.Y.Z-rc.1")

Then commit with the message chore: bump version to X.Y.Z — the auto-release workflow will detect it and create the release.

Verify the Release

After the workflows complete:

# Test binary installation
curl -fsSL https://raw.githubusercontent.com/parallel-web/parallel-web-tools/main/install-cli.sh | bash
parallel-cli --version

# Test Homebrew installation
brew install parallel-web/tap/parallel-cli
parallel-cli --version

# Test PyPI installation
pip install parallel-web-tools[all] --upgrade
parallel-cli --version

Standalone Binaries

Supported Platforms

Platform Runner Archive Name
macOS Apple Silicon macos-15 parallel-cli-darwin-arm64.zip
macOS Intel macos-15-large parallel-cli-darwin-x64.zip
Linux x64 ubuntu-latest parallel-cli-linux-x64.zip
Windows x64 windows-latest parallel-cli-windows-x64.zip

Note: Linux arm64 is not supported (no GitHub-hosted ARM64 runners available).

Binary Size

Expect ~35-50 MB per platform archive (zip). The standalone CLI uses PyInstaller onedir mode for fast startup (~0.2s). The archive extracts to ~80 MB on disk.

PyPI Publishing

First-Time Setup

Configure trusted publishing (no API tokens needed):

  1. Go to https://pypi.org/manage/account/publishing/
  2. Click Add a new pending publisher
  3. Fill in:
    • PyPI project name: parallel-web-tools
    • Owner: parallel-developers
    • Repository: parallel-web-tools
    • Workflow name: publish.yml
    • Environment name: pypi

For Test PyPI (recommended for testing):

  1. Go to https://test.pypi.org/manage/account/publishing/
  2. Same steps, but use environment name: test-pypi

Manual Publishing

To publish without creating a release:

  1. Go to Actions → Publish to PyPI
  2. Click Run workflow
  3. Check "Publish to Test PyPI" for testing
  4. Click Run workflow

Package Extras

The package supports optional dependencies:

pip install parallel-web-tools           # Core library only
pip install parallel-web-tools[cli]      # + CLI tools (click, rich, questionary)
pip install parallel-web-tools[duckdb]   # + DuckDB connector
pip install parallel-web-tools[bigquery] # + BigQuery connector
pip install parallel-web-tools[all]      # Everything

Managing Releases

Delete a Test Release

# Delete release and tag
gh release delete v0.0.1-test --cleanup-tag

# Or separately:
gh release delete v0.0.1-test
git push origin --delete v0.0.1-test

Pre-releases

For testing without affecting "latest":

  1. Create release as usual
  2. Check Set as a pre-release

Pre-releases won't be installed by the install script (which uses GitHub's "latest" release API).

Yanking a PyPI Release

If a release has issues:

# Yank (hide from default install, but still accessible)
pip install twine
twine yank parallel-web-tools==0.0.1

# Or delete entirely (not recommended)
# Must be done via PyPI web interface within 24 hours

Homebrew Tap

The Homebrew formula is published to parallel-web/homebrew-tap.

First-Time Setup

  1. Create the parallel-web/homebrew-tap repository on GitHub
  2. Add a HOMEBREW_TAP_TOKEN secret to this repository — a GitHub PAT with repo scope that has write access to parallel-web/homebrew-tap

The publish-homebrew job in release.yml automatically updates the formula on stable releases (skips RCs). It downloads SHA256 checksums from the release and generates the formula.

Manual Formula Update

# Generate formula from the latest release
python scripts/update-homebrew-formula.py --output homebrew/parallel-cli.rb

# Generate formula for a specific version
python scripts/update-homebrew-formula.py --version 0.1.2 --output homebrew/parallel-cli.rb

CI/CD Workflows

Workflow Trigger Purpose
ci.yml Push to main, PRs Run tests and type checking
auto-release.yml Push to main (version bump commits) Create tag + GitHub Release
release.yml Release created Build binaries, publish to npm + Homebrew
publish.yml Release published Publish to PyPI

Manually Trigger Workflows

# Trigger release build manually
gh workflow run release.yml -f tag=v0.0.1

# Trigger PyPI publish manually
gh workflow run publish.yml -f test_pypi=true

Troubleshooting

Binary build fails

  1. Check the Actions log for the specific platform
  2. Common issues:
    • Missing hidden imports in parallel-web-tools.spec
    • Platform-specific dependency issues

PyPI publish fails

  1. Verify trusted publishing is configured correctly
  2. Check the environment name matches (pypi or test-pypi)
  3. Ensure version number hasn't been used before

Install script fails

  1. Check if zip archives exist on the release
  2. Verify checksum files are present (.zip.sha256)
  3. Test the download URL manually: 
    curl -fsSL https://github.com/parallel-web/parallel-web-tools/releases/download/v0.0.1/parallel-cli-darwin-arm64.zip -o test.zip