copilot-swe-agent[bot]
123 lines
3.7 KiB
Markdown
123 lines
3.7 KiB
Markdown
# Agent Pre-PR Ruff Policy
|
|
|
|
This document defines the policy for Copilot/AI Agents when creating or updating pull requests in the DocuElevate repository.
|
|
|
|
## Required Steps Before Creating/Updating a PR
|
|
|
|
### 1. Run the Ruff Auto-Fix Script
|
|
|
|
Before creating or updating a branch or opening a PR, **ALWAYS** run:
|
|
|
|
```bash
|
|
./scripts/run-ruff-and-fix.sh
|
|
```
|
|
|
|
### 2. Handle Script Exit Codes
|
|
|
|
**If the script exits with code 0 (success):**
|
|
- ✅ All ruff checks passed or were auto-fixed
|
|
- Continue with PR creation process
|
|
- Push the branch (including any auto-fix commits)
|
|
|
|
**If the script exits with code non-zero (failure):**
|
|
- ❌ Stop PR creation immediately
|
|
- Do NOT open the PR
|
|
- Report the ruff failures to the human user
|
|
- Include the full `ruff check` output in your response
|
|
- Create an issue or report the failures for manual resolution
|
|
|
|
### 3. Handle Auto-Fix Commits
|
|
|
|
If the script commits fixes:
|
|
- The script will automatically commit changes with message: `style: ruff auto-fixes`
|
|
- Push the branch with the commit(s) before continuing PR creation
|
|
- This ensures CI sees the fixed code when the PR is opened
|
|
|
|
## Example Agent Workflow
|
|
|
|
```
|
|
1. Clone repository and create feature branch
|
|
2. Make code changes to implement feature
|
|
3. Run: ./scripts/run-ruff-and-fix.sh
|
|
4. Check exit code:
|
|
- If 0: Push branch and create PR
|
|
- If non-zero: Report failures, do NOT create PR
|
|
5. Run project tests (if ruff passed)
|
|
6. If all checks pass: Create the PR
|
|
7. If any check fails: Report failures instead of creating PR
|
|
```
|
|
|
|
## Why This Policy Exists
|
|
|
|
1. **Prevent CI Failures**: Ensures PRs don't break ruff checks in CI
|
|
2. **Auto-Fix Minor Issues**: Automatically fixes formatting and simple linting issues
|
|
3. **Surface Manual Issues Early**: Identifies issues that need human attention before PR creation
|
|
4. **Maintain Code Quality**: Enforces consistent code style across the repository
|
|
|
|
## Integration with Existing CI
|
|
|
|
DocuElevate has two workflows that handle ruff:
|
|
|
|
1. **`.github/workflows/ci.yml`** (Lint Job)
|
|
- Runs `ruff check` (without --fix) on all pushes and PRs
|
|
- Fails CI if issues are found
|
|
- Runs early in the pipeline to catch style issues before tests
|
|
|
|
2. **`.github/workflows/ruff-auto-fix.yml`**
|
|
- Runs on PRs when Python files change
|
|
- Automatically applies `ruff --fix` and `ruff format`
|
|
- Commits fixes back to the PR branch
|
|
- Posts a comment notifying the author
|
|
|
|
This agent script ensures that most issues are caught and fixed **before** the PR is created, reducing the need for the auto-fix workflow to intervene.
|
|
|
|
## Local Development
|
|
|
|
Developers should also use this script or set up pre-commit hooks:
|
|
|
|
```bash
|
|
# Install pre-commit hooks (recommended)
|
|
pip install pre-commit
|
|
pre-commit install
|
|
|
|
# Or run manually before committing
|
|
./scripts/run-ruff-and-fix.sh
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Script fails with "ruff: command not found"
|
|
|
|
The script installs ruff automatically. If this fails:
|
|
```bash
|
|
pip install ruff
|
|
```
|
|
|
|
### Script fails with Git errors
|
|
|
|
Ensure you're in a Git repository with proper configuration:
|
|
```bash
|
|
git config user.name "Your Name"
|
|
git config user.email "your.email@example.com"
|
|
```
|
|
|
|
### Ruff issues remain after --fix
|
|
|
|
Some issues cannot be auto-fixed (e.g., unused imports, complex logic issues). These require manual resolution:
|
|
1. Review the ruff output
|
|
2. Fix the issues manually
|
|
3. Run the script again to verify
|
|
|
|
## Configuration
|
|
|
|
Ruff configuration is in `pyproject.toml` under `[tool.ruff]` and `[tool.ruff.lint]`.
|
|
|
|
Default settings:
|
|
- Line length: 120 characters
|
|
- Target Python version: 3.11+
|
|
- Enabled rules: Pyflakes (F), pycodestyle (E, W), isort (I), bandit (S), flake8-bugbear (B), pylint (PL)
|
|
|
|
## Questions?
|
|
|
|
See the [Contributing Guide](CONTRIBUTING.md) for more information on code quality standards and development workflow.
|