Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
167 lines (113 loc) · 5.61 KB

CONTRIBUTING.md

File metadata and controls

167 lines (113 loc) · 5.61 KB
Raw

Contributing to Generalized Notation Notation (GNN)

Thank you for your interest in contributing to GNN! This project benefits from contributions of all kinds — from bug reports and documentation improvements to new pipeline modules and framework integrations.

Getting Started

Prerequisites

  • Python 3.11+
  • UV package manager (installation)
  • Git for version control

Setup

# Fork and clone the repository
git clone https://github.com/<your-username>/GeneralizedNotationNotation.git
cd GeneralizedNotationNotation

# Install dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

# Run the test suite to verify your setup
uv run pytest src/tests/ -v

See SETUP_GUIDE.md for detailed installation instructions including optional dependency groups.

How to Contribute

Reporting Bugs

  1. Search existing issues first.
  2. If no existing issue matches, open a new one with:
    • A clear, descriptive title
    • Steps to reproduce
    • Expected vs. actual behavior
    • Python version, OS, and relevant dependency versions

Suggesting Features

Open a GitHub Discussion or issue describing:

  • The problem the feature would solve
  • Your proposed approach
  • Any relevant examples or references

Submitting Code Changes

  1. Fork the repository and create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes following the conventions below.

  3. Run the tests to ensure nothing is broken:

    uv run pytest src/tests/ -v

  4. Commit with clear, descriptive messages:

    git commit -m "Add support for new matrix type in GNN parser"

  5. Push to your fork and open a Pull Request against main.

Code Conventions

Architecture

All pipeline modules follow the thin orchestrator pattern:

  • Numbered scripts (src/N_module.py): Handle CLI args, logging, and delegation only (<150 lines)
  • Module directories (src/module/): Contain all domain logic in processor.py, public API in __init__.py

Code Standards

  • Type hints for all public functions
  • Exit codes: 0 = success, 1 = error, 2 = warnings
  • Tests exercise real code paths and real data dependencies
  • Follow existing patterns — read neighboring modules before writing new ones

Module Structure

Every module must include:

src/module_name/
  __init__.py      # Public API
  processor.py     # Core logic
  AGENTS.md        # Module documentation
  mcp.py           # MCP tool registration (if applicable)

Testing

  • Tests go in src/tests/test_{module}_*.py
  • Run module-specific tests: uv run pytest src/tests/test_gnn_*.py -v
  • Check coverage: uv run pytest --cov=src --cov-report=term-missing
  • Aim for >80% test coverage on new code

Documentation

  • Update AGENTS.md in the relevant module directory
  • If adding a pipeline step, update AGENTS.md, DOCS.md, and README.md
  • Use concrete examples and real outputs over promotional language

CI and automation

Pull requests against main run the workflows described in .github/README.md: tests and lint (with path filters), docs audit when Markdown or doc/ changes, dependency review, CodeQL, and workflow lint when .github/workflows/** changes.

Before opening a PR, align locally where possible:

# Using just (recommended)
just lint                  # Ruff lint check
just test                  # Fast test suite
just test-mod MODULE       # Test specific module

# Or manually
uv sync --frozen --extra dev
uv run pytest -m "not pipeline and not mcp" --tb=short -q
uv run ruff check src/
uv run python doc/development/docs_audit.py --strict

For workflow YAML edits, run actionlint .github/workflows/*.yml (see the hub doc for install options). Full suite (including pipeline/MCP-marked tests) is heavier than CI; use uv run pytest src/tests/ -v when your change touches those areas.

Pull Request Guidelines

  • Keep PRs focused on a single change
  • Include a description of what changed and why
  • Reference any related issues (e.g., "Fixes #42")
  • Ensure all tests pass before requesting review
  • Update documentation if your change affects user-facing behavior

Style Guide

Follow the project Style Guide for formatting and naming conventions. Key points:

  • Python code follows PEP 8
  • GNN files use Markdown with structured sections (see GNN Syntax)
  • Commit messages should be imperative ("Add feature" not "Added feature")

Security

Security considerations

If you discover a security vulnerability, please follow the reporting process in SECURITY.md. Do not open a public issue for security vulnerabilities.

Code of Conduct

Please review and follow our Code of Conduct. We are committed to providing a welcoming and inclusive experience for everyone.

Recognition

Contributors are recognized in release notes, the CHANGELOG, and the contributors graph.

Questions?