Skip to content

contributing.md

Latest commit

 

History

History
159 lines (117 loc) · 4.39 KB

contributing.md

File metadata and controls

159 lines (117 loc) · 4.39 KB
Raw
title Contributing

Contributing

Guidelines for contributing to the QuantEcon Style Guide Checker.

Development Setup

Prerequisites

  • uv (handles Python, venv, and deps for you)
  • Git
  • GitHub account

Local Development

# Clone
git clone https://github.com/QuantEcon/action-style-guide.git
cd action-style-guide

# uv reads pyproject.toml + uv.lock and creates a .venv automatically.
# --all-extras installs PyGithub (action) + pytest/ruff (dev).
uv sync --all-extras

# Run commands via `uv run` (no need to activate the venv):
uv run qestyle --version
uv run pytest tests/

# Set up API keys
export ANTHROPIC_API_KEY="your-key"
export GITHUB_TOKEN="your-token"

Don't want uv? You can still use pip install -e ".[dev,action]" — the dependency manifest is the same. uv just makes installs faster and reproducible via uv.lock.

Code Style

  • Follow PEP 8
  • Use type hints
  • Add docstrings to all functions/classes
  • Keep functions focused and small
  • Comment complex logic (explain "why", not "what")

Guiding Principles

  1. Simplicity above all — write the simplest code that works
  2. Direct over abstract — don't abstract until you have 3+ use cases
  3. Readable over concise — explicit is better than implicit
  4. Less code = less bugs — every line is a liability
# Good: Simple, clear, explicit
def apply_fix(content: str, violation: dict) -> str:
    """Apply a single fix to content."""
    old_text = violation['current_text']
    new_text = violation['suggested_fix']
    return content.replace(old_text, new_text, 1)

# Avoid: Clever, requires mental parsing
def apply_fix(c, v):
    return c.replace(v['ct'], v['sf'], 1) if 'ct' in v and 'sf' in v else c

Adding New Rules

Rules are in style_checker/rules/ and are read directly by the LLM — no code changes needed.

  1. Edit the appropriate rules file (e.g., style_checker/rules/writing-rules.md)

  2. Follow the existing format:

    ### Rule: qe-writing-001
**Type:** rule
**Title:** Use one sentence per paragraph

**Description:**
[Detailed explanation]

**Check for:**
[Specific patterns to identify]

**Examples:**
[Good and bad examples]

  3. The base prompt (prompts/prompt.md) is shared across all categories; usually no edit needed there.

  4. Test with real lecture files

Adding a New Category

  1. Create style_checker/rules/{category}-rules.md
  2. Add the new name to VALID_CATEGORIES in style_checker/categories.py
  3. Add an entry for it in RULE_EVALUATION_ORDER in style_checker/reviewer.py (the test suite will fail loudly if the keys drift)
  4. Test end-to-end

Pull Request Process

  1. Fork the repository
  2. Create feature branch: git checkout -b feature/your-feature-name
  3. Make changes — write clean, documented code
  4. Run tests: pytest tests/ -v
  5. Commit with clear messages using conventional commits
  6. Push and create PR with clear description

Commit Message Format

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • refactor: Code refactoring
  • test: Adding tests
  • chore: Maintenance tasks

Version Management

The version lives in one place — style_checker/__init__.py:

# In __init__.py — bump for every release
__version__ = "0.7.2"

pyproject.toml reads it via [tool.setuptools.dynamic] version = {attr = "style_checker.__version__"}, so pip install qestyle and qestyle --version always report the same number.

Release Process

  1. Make changes
  2. Run full test suite: uv run pytest tests/ -v
  3. Update __version__ in style_checker/__init__.py
  4. Regenerate the lockfile: uv lock (commit the diff)
  5. Update prompt versions if prompts were modified
  6. Update CHANGELOG.md
  7. Commit: Release vX.Y.Z - Description
  8. Create GitHub release: gh release create vX.Y.Z
  9. Update floating tag: git tag -f v0.7 && git push origin v0.7 --force

Debugging LLM Issues

  1. Check the prompt — is it clear and explicit?
  2. Add more examples to rules
  3. Strengthen language (e.g., "do NOT" instead of "don't")
  4. Add "Important:" or "Critical:" sections
  5. Test with isolated examples first

Reporting Issues

Include:

  1. Description of the problem
  2. Steps to reproduce
  3. Expected vs actual behavior
  4. Environment details (OS, Python version)
  5. Relevant logs or error messages