Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
107 lines (86 loc) · 4.89 KB

CONTRIBUTING.md

File metadata and controls

107 lines (86 loc) · 4.89 KB
Raw

How to contribute to incoming-extractor

Thank you for your interest in contributing to incoming-extractor! Please follow these guidelines to help maintain code quality and consistency.

General Guidelines

  • Follow the coding standards and rules described below for each file type.
  • Ensure all code passes linting and tests before submitting a pull request.
  • Write clear commit messages and document your changes in the changelog if relevant.
  • Contributors are listed in package.json and pyproject.toml.
  • Update relevant fields in .wiswa.jsonnet such as authors, dependencies, etc.
  • All contributed code must have a license compatible with the project's license (MIT).
  • Add missing words to .vscode/dictionary.txt as necessary (sorted and lower-cased).

Development Environment

  • Use uv to manage Python dependencies:
    • Install dependencies: uv sync
    • Add a dependency: uv add <package>
    • Add a dev dependency: uv add --group dev <package>
    • Add a test dependency: uv add --group tests <package>
    • Add a docs dependency (rarely needed): uv add --group docs <package>
  • Use Yarn to install Node.js based dependencies:
    • Install Node.js dependencies: yarn
  • Install pre-commit and make sure it is enabled by running pre-commit install in the repository checkout.

Quality Assurance & Scripts

The following scripts are available via yarn (see package.json):

  • yarn qa: Run all QA checks (type checking, linting, spelling, formatting).
  • yarn test: Run the test suite.
  • yarn test:cov: Run tests with coverage report.
  • yarn ruff / yarn ruff:fix: Run Ruff linter (and auto-fix).
  • yarn mypy: Run Mypy type checker.
  • yarn check-formatting: Check code formatting.
  • yarn format: Auto-format code.
  • yarn check-spelling: Run spell checker.
  • yarn gen-docs: Build HTML documentation.
  • yarn gen-manpage: Build the man page from Sphinx sources under docs/ (do not edit man/wiswa.1 or other generated files under man/ by hand). After changing CLI or narrative docs, run this and commit the updated man/ output.

The above all need to pass for any code changes to be accepted.

Python Code Guidelines

  • Follow Ruff linting rules, with specific exceptions (see the Python instructions).
  • Always use type hints in function and method signatures, including tests.
  • Use 4 spaces for indentation.
  • Use snake_case for variables and functions, CamelCase for classes, and UPPER_SNAKE_CASE for constants.
  • Use single quotes for strings and double quotes for docstrings only.
  • Add from __future__ import annotations at the top of every file (this will be done by Ruff in VS Code if you have the extension installed).
  • Keep imports sorted and grouped: future, standard library, third-party, local (also done by Ruff).
  • Prefer latest Python features (3.10+).
  • For subprocess, avoid shell=True and check=False.
  • Alias subprocess as import subprocess as sp.
  • Add public-facing API elements to __all__. Prefer not to use underscore-prefix except in 'private' method names. Do not create class attributes that invoke name mangling.
  • See Python instructions for full details.

Python Tests Guidelines

  • Use pytest for testing.
  • All test functions must start with test_ and test files as test_*.py.
  • Always add type hints, including return values.
  • Use fixtures from tests/conftest.py only.
  • Use @pytest.mark.parametrize for parametrised tests and @pytest.mark.asyncio for async tests.
  • Do not add docstrings to test functions.
  • Mock external dependencies and I/O operations.
  • Strive to keep the coverage level the same or higher.
  • Use # pragma: no cover when appropriate.
  • See Python tests instructions for more details.

Markdown Guidelines

  • <kbd> tags are allowed.
  • Headers do not have to be unique if in different sections.
  • Line length rules do not apply to code blocks.
  • See Markdown instructions for more.

JSON, YAML, TOML, INI Guidelines

  • JSON and YAML files should generally be recursively sorted by key.
  • In TOML/INI, = must be surrounded by a single space on both sides.
  • See JSON/YAML guidelines and TOML/INI guidelines for more details.

Submitting Changes

Do not submit PRs solely for dependency bumps. Dependency bumps are either handled by running Wiswa locally or allowing Dependabot to do them.

  1. Fork the repository and create your branch from master.
  2. Ensure your code follows the above guidelines.
  3. Run all tests (yarn test) and QA scripts (yarn qa). Be certain pre-commit runs on your commits.
  4. Submit a pull request with a clear description of your changes.