Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
87 lines (57 loc) · 3.67 KB

CONTRIBUTING.md

File metadata and controls

87 lines (57 loc) · 3.67 KB
Raw

Contributing to mloda-plugin-template

Thanks for considering a contribution to the template repo itself. This document is for people who want to improve the scaffold (CI workflows, examples, dev tooling, docs) that downstream plugin authors will inherit.

If you arrived here after clicking "Use this template" on GitHub: this file does not apply to your new plugin repo. Follow the README's Use this template section, which includes a step that removes this file along with the other template-only community files.

By participating in this project, you agree to abide by the Code of Conduct.

Getting Started

Prerequisites

  • Python 3.10 or higher
  • uv for dependency management
  • tox for running checks (installed via the dev extras)

Local Development Setup

  1. Fork the repository and clone your fork:
git clone https://github.com/<your-username>/mloda-plugin-template.git
cd mloda-plugin-template
  1. Create the virtualenv and install dependencies:
uv venv
source .venv/bin/activate
uv sync --all-extras
  1. Verify your setup by running the full check suite:
tox

Code Style

tox is the gate. It runs:

  • pytest for tests
  • ruff format --check --line-length 120 for formatting
  • ruff check for linting
  • mypy --strict --ignore-missing-imports for type checking
  • bandit -c pyproject.toml -r -q for security

All of these must pass before a PR is mergeable. A separate tox -e security environment runs pip-audit for CVE scanning of installed dependencies.

Conventions

  • Type hints: use modern forms (list[str], dict[str, int], X | None).
  • Line length: 120.
  • Tests: every new feature or bug fix must come with tests; follow the patterns in tests/ and placeholder/.../tests/.
  • Commits: use Conventional Commits (feat:, fix:, chore:, docs:, test:, refactor:, style:, ci:, build:, perf:). semantic-release uses standard rules: feat: triggers a minor bump, all others trigger a patch (see .releaserc.yaml).
  • No Co-Authored-By lines or other AI agent mentions in commit messages or PR descriptions.

Pull Request Workflow

  1. Create a feature branch from main:
git checkout -b fix/short-description
  1. Make your changes; run tox locally and confirm it passes.
  2. Commit using Conventional Commits format.
  3. Push to your fork and open a pull request targeting main.
  4. CI runs the full tox suite. All checks must pass before merge.

Reporting Issues

Use the issue form at .github/ISSUE_TEMPLATE/issue.yml. It asks for a one-sentence summary, reproduction or motivation, optional code pointers, and an optional definition of done. See the Issue Creation section in AGENTS.md for more guidance.

Plugin Development vs. Template Contribution

This repo is the scaffold for new mloda plugins, not a plugin itself. If you want to:

License

By contributing, you agree that your contributions will be licensed under the Apache License, Version 2.0.