Skip to content

Contributing

Contributions to mono are welcome! This template is designed to be minimal and production-ready, so please keep that philosophy in mind when proposing changes.

Project Philosophy

Before contributing, understand these core principles:

  1. Minimal by Design - Only include features that are essential for most CLI tools
  2. Template-First - Everything should be easy to customize and extend
  3. Modern Best Practices - Use current Python standards (as of 2025)
  4. Production-Ready - CI/CD, testing, and docs should work out of the box
  5. Well-Documented - Every feature should be clearly explained

What to Contribute

✅ Good Contributions

  • Bug fixes in the template structure
  • Improvements to documentation
  • Better examples in the usage guide
  • CI/CD workflow improvements
  • Tool configuration optimizations
  • Adding essential features that 80%+ of CLI tools need

⚠️ Carefully Consider

  • New dependencies (keep the template lightweight)
  • Complex features (most users should add these themselves)
  • Opinionated patterns (the template should be flexible)

❌ Please Don't

  • Add features specific to certain use cases
  • Include heavy dependencies without strong justification
  • Make the template harder to understand or customize
  • Break the minimalist philosophy

Development Setup

1. Clone the Repository

git clone https://github.com/guenp/mono.git
cd mono

2. Install Dependencies

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install all dependencies including dev and docs groups
uv sync --group dev --group docs

3. Install Pre-commit Hooks

uv run pre-commit install

4. Verify Setup

# Run tests
uv run pytest

# Try the CLI
uv run python -m mono
# Output: Hello, World!

Running Tests

Run the test suite:

# All tests
uv run pytest

# With coverage report
uv run pytest --cov=mono --cov-report=term-missing

# Specific test file
uv run pytest tests/test_mono.py

# Specific test
uv run pytest tests/test_mono.py::test_hello_default

# Verbose output
uv run pytest -v

The template includes basic tests for the example hello command. When adding features to the template, add corresponding tests.

Code Quality

The project uses modern Python tooling to maintain code quality:

Formatting

# Format all code
uv run ruff format .

# Check what would be formatted
uv run ruff format --check .

Linting

# Lint all code
uv run ruff check .

# Auto-fix issues
uv run ruff check --fix .

Type Checking

# Type check all code
uv run mypy src tests

# Specific file
uv run mypy src/mono/cli.py

Run All Checks

Pre-commit runs all checks automatically before commits:

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

# Update pre-commit hook versions
uv run pre-commit autoupdate

Project Structure

.
├── .github/
│   └── workflows/
│       ├── pytest.yml       # Run tests on push/PR
│       ├── release.yml      # Publish to PyPI on tags
│       └── docs.yml         # Deploy docs to GitHub Pages
├── docs/
│   ├── index.md            # Main documentation page
│   ├── getting-started.md  # Installation and quickstart
│   ├── usage.md            # Usage examples and patterns
│   └── contributing.md     # This file
├── src/
│   └── mono/
│       ├── __init__.py     # Package initialization, version
│       ├── cli.py          # Typer CLI application
│       └── _version.py     # Auto-generated by hatch-vcs
├── tests/
│   ├── conftest.py         # Pytest configuration
│   └── test_mono.py        # CLI tests
├── pyproject.toml          # Package metadata and tool config
├── zensical.toml           # Documentation site config
├── CLAUDE.md               # AI assistant development notes
└── README.md               # User-facing documentation

Making Changes

Adding a New Feature

  1. Discuss First - Open an issue to discuss whether the feature fits the template's philosophy
  2. Update Code - Make changes to src/mono/
  3. Add Tests - Add corresponding tests in tests/
  4. Update Docs - Document the feature in docs/usage.md
  5. Run Checks - Ensure all quality checks pass
  6. Update Examples - Add examples to README if relevant

Improving Documentation

Documentation improvements are always welcome:

  • Fix typos or unclear explanations
  • Add more examples to docs/usage.md
  • Improve quickstart instructions in docs/getting-started.md
  • Enhance the README with better examples
  • Update CLAUDE.md with development insights

Testing Documentation

Build and view docs locally:

# Build documentation
uv run zensical build

# Serve documentation locally (with hot reload)
uv run zensical serve

Then visit http://localhost:8000 to preview changes.

Pull Request Process

1. Fork and Branch

# Fork the repo on GitHub, then:
git clone https://github.com/YOUR_USERNAME/mono.git
cd mono

# Create a feature branch
git checkout -b feature/my-improvement

2. Make Changes

# Make your changes
# Run tests and checks
uv run pytest
uv run ruff format .
uv run ruff check .
uv run mypy src tests

3. Commit

Write clear, concise commit messages:

git add .
git commit -m "Add example for file processing commands

- Add file processing example to usage.md
- Include error handling pattern
- Add corresponding test case"

4. Push and Create PR

git push origin feature/my-improvement

Then open a pull request on GitHub with: - Clear title describing the change - Description explaining what and why - Tests showing the changes work - Screenshots if relevant (for docs changes)

5. Review Process

  • Maintainers will review your PR
  • Address any feedback or requested changes
  • Once approved, your PR will be merged!

Release Process

Releases are automated via GitHub Actions:

  1. Maintainer creates and pushes a version tag (e.g., v0.2.0)
  2. GitHub Actions automatically:
  3. Runs all tests
  4. Builds the package
  5. Publishes to PyPI
  6. Creates a GitHub release
# Create a new release (maintainers only)
git tag v0.2.0
git push origin v0.2.0

Version numbers follow semantic versioning: - MAJOR: Breaking changes - MINOR: New features (backwards compatible) - PATCH: Bug fixes

Tech Stack

The template uses minimal, modern dependencies:

Core: - Python 3.12+ - Modern Python features - Typer - CLI framework (built on Click)

Development: - pytest - Testing framework - pytest-cov - Coverage reporting - mypy - Static type checker - ruff - Fast linter and formatter - pre-commit - Git hook framework

Documentation: - Zensical - Documentation builder - markdown-gfm-admonition - Enhanced markdown

Build: - hatchling - Modern build backend - hatch-vcs - Version from git tags - uv - Fast package installer

Questions or Issues?

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank You!

Every contribution, no matter how small, helps make mono better for everyone. Thank you for taking the time to contribute! 🎉