From 11aa3d78cc222042f6ef64f0122a322a6a7d7f56 Mon Sep 17 00:00:00 2001 From: Matt McKay Date: Fri, 5 Jun 2026 15:04:51 +1000 Subject: [PATCH 1/2] =?UTF-8?q?chore:=20housekeeping=20=E2=80=94=20example?= =?UTF-8?q?s=20pin,=20doc=20fixes,=20import=20cleanup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wraps up the remaining low-risk tidy-ups from TECHNICAL-REVIEW plus a docs review. - ยง7.1: bump examples/*.yml action pin @v0.3 -> @v0.7 (the long-stale pin; docs/user/* already use v0.7). 2 files. - ยง8.9: hoist the 4 lazy `from . import __version__` calls in github_handler.py to a single module-top import. No circular import to avoid; module imports cleanly. - CONTRIBUTING.md: the root file was a stale duplicate with broken instructions (`pip install -r requirements.txt` and `python -m style_checker.main --mode single` โ€” neither exists after the uv migration / action.py rename). Replaced with a concise, correct quick-start that defers to the canonical docs/developer/contributing.md. - .github/copilot-instructions.md: version example 0.6.1 -> 0.7.2; `pytest` -> `uv run pytest`; stale `v0.3` release-tag example -> a `vX.Y` placeholder consistent with the surrounding `vX.Y.Z` steps. - CHANGELOG: note the examples pin bump under [Unreleased]. Tests: 87 passed; ruff clean; example workflows still parse. Co-Authored-By: Claude Opus 4.8 --- .github/copilot-instructions.md | 6 +- CHANGELOG.md | 1 + CONTRIBUTING.md | 220 +++++++------------------------ examples/style-guide-comment.yml | 2 +- examples/style-guide-weekly.yml | 2 +- style_checker/github_handler.py | 5 +- 6 files changed, 52 insertions(+), 184 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1c59480..c695872 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -151,7 +151,7 @@ assert github_token ```python # In __init__.py -__version__ = "0.6.1" # Bump for every release +__version__ = "0.7.2" # Bump for every release # In action.py - print version at startup print(f"๐Ÿ“‹ QuantEcon Style Guide Checker v{__version__}") @@ -162,7 +162,7 @@ print(f"๐Ÿ“‹ QuantEcon Style Guide Checker v{__version__}") **CRITICAL: Always run tests before any release!** 1. Make changes -2. **Run full test suite**: `pytest tests/ -v` +2. **Run full test suite**: `uv run pytest tests/ -v` 3. **Verify all tests pass** (except LLM integration tests which require API keys) 4. Update `__version__` in `style_checker/__init__.py` 5. **Update prompt versions** if any prompts were modified: @@ -172,7 +172,7 @@ print(f"๐Ÿ“‹ QuantEcon Style Guide Checker v{__version__}") 6. Update `CHANGELOG.md` (move Unreleased to new version) 7. Commit: "Release vX.Y.Z - Description" 8. Create GitHub release: `gh release create vX.Y.Z --title "..." --notes "..."` -9. Update floating tag: `git tag -f v0.3 && git push origin v0.3 --force` +9. Update floating tag (current minor, e.g. `v0.7`): `git tag -f vX.Y && git push origin vX.Y --force` 10. Push main branch: `git push origin main` **Never skip testing** - it catches regressions and ensures quality. diff --git a/CHANGELOG.md b/CHANGELOG.md index 51c28a8..9c8c3a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - **Bumped GitHub Actions to Node 24-compatible versions** โ€” GitHub forces Node 24 as the default runner runtime from 2026-06-02 (Node 20 fully removed 2026-09-16). Updated `actions/checkout@v4โ†’v5` and `astral-sh/setup-uv@v3โ†’v7` in `action.yml` and CI; the docs workflow now uses `actions/setup-node@v4โ†’v6` (Node 22), `actions/upload-pages-artifact@v3โ†’v5`, and `actions/deploy-pages@v4โ†’v5`. Resolves #16. +- **Bumped example workflows to `@v0.7`** โ€” `examples/style-guide-comment.yml` and `examples/style-guide-weekly.yml` pinned the action at the long-stale `@v0.3`; they now track the current `v0.7` release line, matching the `docs/user/*` snippets. ## [0.7.2] - 2026-02-16 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb90b67..da2b7c6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,209 +1,79 @@ # Contributing to QuantEcon Style Guide Checker -Thank you for your interest in contributing! This document provides guidelines for contributing to the project. +Thank you for your interest in contributing! ๐ŸŽ‰ -## Development Setup +> **๐Ÿ“– Full developer guide:** The complete, up-to-date guide โ€” development +> setup, adding rules and categories, testing, and the release process โ€” lives +> in [`docs/developer/contributing.md`](docs/developer/contributing.md). This +> page is a quick summary. -### Prerequisites +## Quick Start -- Python 3.11+ -- Git -- GitHub account - -### Local Development - -1. **Clone the repository** - ```bash - git clone https://github.com/QuantEcon/action-style-guide.git - cd action-style-guide - ``` - -2. **Create virtual environment** - ```bash - python -m venv venv - source venv/bin/activate # On Windows: venv\Scripts\activate - ``` - -3. **Install dependencies** - ```bash - pip install -r requirements.txt - pip install -r requirements-dev.txt # If available - ``` - -4. **Set up API keys** - ```bash - export ANTHROPIC_API_KEY="your-key" # For Claude Sonnet 4.5 - export GITHUB_TOKEN="your-token" # For GitHub API - ``` - -## Testing Locally - -### Test Single Lecture Review +The project uses [uv](https://docs.astral.sh/uv/) to manage Python, the +virtualenv, and dependencies. ```bash -python -m style_checker.main \ - --mode single \ - --lectures-path lectures/ \ - --repository owner/repo \ - --comment-body "@qe-style-checker lecture-name" \ - --create-pr false -``` +git clone https://github.com/QuantEcon/action-style-guide.git +cd action-style-guide -### Test Bulk Review +# uv reads pyproject.toml + uv.lock and creates a .venv automatically. +# --all-extras installs PyGithub (action) + pytest/ruff (dev). +uv sync --all-extras -```bash -python -m style_checker.main \ - --mode bulk \ - --lectures-path lectures/ \ - --repository owner/repo \ - --create-pr false +# Run commands via `uv run` (no need to activate the venv): +uv run qestyle --version +uv run pytest tests/ ``` -## Adding New Features - -### Adding New Style Rules - -Rules are now organized in category-specific files in `style_checker/rules/`: - -1. Edit the appropriate rules file (e.g., `style_checker/rules/writing-rules.md`) -2. Add rule following the existing Markdown format: - ```markdown - ## Rule Title - - **Description**: Clear explanation of what the rule checks - - **Why**: Rationale for this rule - - **Good**: - ```python - # Good example - ``` - - **Bad**: - ```python - # Bad example - ``` - ``` - -3. Rules are grouped into 8 categories: - - writing, math, code, jax, figures, references, links, admonitions - -4. If needed, update corresponding prompt file in `style_checker/prompts/` - -5. Test with sample lectures - -### Adding New LLM Providers - -The action currently uses Claude Sonnet 4.5 via the Anthropic API. The provider logic is in `style_checker/reviewer.py`. +Prefer pip? `pip install -e ".[dev,action]"` uses the same dependency manifest. -To switch or add a provider: -1. Update the API client setup in `AnthropicProvider.__init__()` -2. Adjust model name and parameters as needed -3. Update `requirements.txt` with new dependencies -4. Test with real lecture files +To run against real lectures, set your API keys first: -### Improving Prompts - -The action uses a focused prompts architecture: -- **Prompts** (`style_checker/prompts/*.md`): Concise instructions for the LLM -- **Rules** (`style_checker/rules/*.md`): Detailed specifications with examples - -To improve: -- Edit the appropriate prompt or rules file -- Test with various lecture types -- Ensure Markdown output format is maintained -- Validate against all rule categories - -## Code Style - -- Follow PEP 8 -- Use type hints -- Add docstrings to all functions/classes -- Keep functions focused and small -- Comment complex logic - -## Pull Request Process - -1. **Fork the repository** -2. **Create feature branch** - ```bash - git checkout -b feature/your-feature-name - ``` - -3. **Make changes** - - Write clean, documented code - - Add tests if applicable - - Update documentation +```bash +export ANTHROPIC_API_KEY="your-key" # Claude (Anthropic) +export GITHUB_TOKEN="your-token" # GitHub API +``` -4. **Test thoroughly** - - Test locally with real lectures - - Verify PR creation works - - Check all output formats +## Adding Style Rules -5. **Commit with clear messages** - ```bash - git commit -m "feat: add feature description" - ``` +Rules live in `style_checker/rules/*.md` and are read directly by the LLM โ€” **no +code change is needed** to add a rule to an existing category. Adding a whole new +category also requires updating `VALID_CATEGORIES` +(`style_checker/categories.py`) and `RULE_EVALUATION_ORDER` +(`style_checker/reviewer.py`); the test suite fails loudly if those drift. See +the [full guide](docs/developer/contributing.md#adding-new-rules) for the rule +format and details. -6. **Push and create PR** - ```bash - git push origin feature/your-feature-name - ``` +## Pull Requests -7. **PR Requirements** - - Clear description of changes - - Reference any related issues - - Include test results - - Update README if needed +1. Fork the repository and create a feature branch: + `git checkout -b feature/your-feature-name` +2. Make your changes; add tests where it makes sense. +3. Run the suite: `uv run pytest tests/` +4. Commit using conventional commits (below) and open a PR with a clear + description that references any related issues. -## Commit Message Format +### Commit Message Format -Use conventional commits: +Use [conventional commits](https://www.conventionalcommits.org/): - `feat:` New feature - `fix:` Bug fix - `docs:` Documentation changes -- `style:` Code style changes (formatting) +- `style:` Code style / formatting - `refactor:` Code refactoring - `test:` Adding tests - `chore:` Maintenance tasks ## Reporting Issues -When reporting issues, include: - -1. **Description** of the problem -2. **Steps to reproduce** -3. **Expected behavior** -4. **Actual behavior** -5. **Environment details** (OS, Python version, etc.) -6. **Relevant logs** or error messages +Include: a description of the problem, steps to reproduce, expected vs. actual +behavior, environment details (OS, Python version), and any relevant logs or +error messages. ## Suggesting Enhancements -For feature requests: - -1. **Use case**: Why is this needed? -2. **Proposed solution**: How should it work? -3. **Alternatives considered**: Other approaches? -4. **Implementation ideas**: Technical approach? - -## Style Guide Rules - -When adding or modifying style guide rules: - -1. **Clear and specific**: Rules should be unambiguous -2. **Actionable**: Include examples of correct/incorrect usage -3. **Categorized properly**: Use one of the 8 categories (writing, math, code, jax, figures, references, links, admonitions) -4. **Typed correctly**: - - `rule`: Actionable, automatically applied - - `style`: Advisory, requires human judgment - - `migrate`: Legacy pattern modernization - -## Questions? - -- Open a discussion on GitHub -- Check existing issues and PRs -- Review the documentation +Open a GitHub discussion or issue describing the use case, your proposed +solution, and any alternatives you considered. Thank you for contributing! ๐ŸŽ‰ diff --git a/examples/style-guide-comment.yml b/examples/style-guide-comment.yml index f2e7014..9c4461f 100644 --- a/examples/style-guide-comment.yml +++ b/examples/style-guide-comment.yml @@ -32,7 +32,7 @@ jobs: }) - name: Run style guide checker - uses: QuantEcon/action-style-guide@v0.3 + uses: QuantEcon/action-style-guide@v0.7 with: mode: 'single' lectures-path: 'lectures/' diff --git a/examples/style-guide-weekly.yml b/examples/style-guide-weekly.yml index 244377a..54b3995 100644 --- a/examples/style-guide-weekly.yml +++ b/examples/style-guide-weekly.yml @@ -17,7 +17,7 @@ jobs: steps: - name: Run bulk style guide review - uses: QuantEcon/action-style-guide@v0.3 + uses: QuantEcon/action-style-guide@v0.7 id: review with: mode: 'bulk' diff --git a/style_checker/github_handler.py b/style_checker/github_handler.py index 47af966..2cead5f 100644 --- a/style_checker/github_handler.py +++ b/style_checker/github_handler.py @@ -11,6 +11,7 @@ from github import Github, GithubException from datetime import datetime +from . import __version__ from .categories import VALID_CATEGORIES @@ -298,7 +299,6 @@ def format_detailed_report(self, review_result: Dict[str, Any], lecture_name: st Returns: Detailed markdown report with all violations (wrapped in
) """ - from . import __version__ # Wrap in collapsible details block report = f"
\n๐Ÿ“Š Detailed Style Review Report (click to expand)\n\n" @@ -374,7 +374,6 @@ def format_applied_fixes_report(self, review_result: Dict[str, Any], lecture_nam Returns: Detailed markdown report of applied fixes (wrapped in
) """ - from . import __version__ fix_log = review_result.get('fix_log', []) original_content = review_result.get('original_content', '') @@ -445,7 +444,6 @@ def format_style_suggestions_report(self, review_result: Dict[str, Any], lecture Returns: Open markdown report of style suggestions (NOT collapsible - visible by default) """ - from . import __version__ style_violations = review_result.get('style_violations', []) @@ -508,7 +506,6 @@ def format_pr_body(self, review_result: Dict[str, Any], lecture_name: str) -> st Returns: Concise PR body with summary """ - from . import __version__ body = f"## ๐Ÿ“‹ Style Guide Review: {lecture_name}\n\n" body += f"This PR addresses style guide compliance issues found in the `{lecture_name}` lecture.\n\n" From d148159caab15014045bb02642d6f8194cf83e67 Mon Sep 17 00:00:00 2001 From: Matt McKay Date: Fri, 5 Jun 2026 15:17:42 +1000 Subject: [PATCH 2/2] fix: add missing id to checker step in comment-trigger example The "Run style guide checker" step lacked `id: run-checker`, but a later step references `steps.run-checker.outputs.pr-url`. Without the id that reference resolves to an empty string, so the success message with the PR link never fired (the workflow always posted "no PR created"). Adds `id: run-checker` to match the existing reference, mirroring the working style-guide-weekly.yml example. Addresses Copilot review feedback on #24. Co-Authored-By: Claude Opus 4.8 --- examples/style-guide-comment.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/examples/style-guide-comment.yml b/examples/style-guide-comment.yml index 9c4461f..560d5ba 100644 --- a/examples/style-guide-comment.yml +++ b/examples/style-guide-comment.yml @@ -32,6 +32,7 @@ jobs: }) - name: Run style guide checker + id: run-checker uses: QuantEcon/action-style-guide@v0.7 with: mode: 'single'