Pull requests are welcome! By participating in this project, you agree to abide by our code of conduct.

Fork and then clone the repository:

# replace <USER> with your username
git clone git@github.com:<USER>/python-cli-template.git

cd python-cli-template

Install uv:

brew install uv

Install development dependencies:

uv sync --all-extras

Install pre-commit into your git hooks:

uv run pre-commit install

Make your changes, add tests/documentation, and ensure tests pass.

Write a commit message that follows the Conventional Commits specification:

• feat: A new feature
• fix: A bug fix
• perf: A code change that improves performance
• refactor: A code change that neither fixes a bug nor adds a feature
• test: Add missing tests or correct existing tests
• build: Changes that affect the build system or external dependencies
• ci: Updates configuration files and scripts for continuous integration
• docs: Documentation only changes

Push to your fork and create a pull request.

At this point, wait for us to review your pull request. We'll try to review pull requests within 1-3 business days. We may suggest changes, improvements, and/or alternatives.

Things that will improve the chance that your pull request will be accepted:

• Write tests that pass CI.
• Write solid documentation.
• Write a good commit message.

Install test dependencies:

uv sync --extra test

Run the tests:

uv run pytest

Run the tests with coverage:

uv run coverage run -m pytest

Generate a coverage report:

uv run coverage report

uv run coverage html

Install the package with uv:

uv tool install . --force

Test the command:

python-cli-template --help

Install lint dependencies:

uv sync --extra lint

Update pre-commit hooks to the latest version:

uv run pre-commit autoupdate

Run all pre-commit hooks:

uv run pre-commit run --all-files

Lint all files:

uv run ruff check # --fix

Format all files:

uv run ruff format

Run type checking:

uv run mypy .

Run the CLI:

uv run python-cli-template

Install build dependencies:

uv sync --extra build

Generate the distribution packages:

uv build

Upload all of the archives under dist:

uv publish --repository testpypi

Install the package:

uv tool install --index-url testpypi python-cli-template

Bundle the package with PyInstaller:

uv run pyinstaller python_cli_template.cli --name python-cli-template

Install docs dependencies:

uv sync --extra docs

Generate the docs with pdoc:

uv run pdoc src/python_cli_template/

Release and publish are automated with Release Please.

Add a new pending publisher to PyPI.