diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 286a884..2b5a318 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -243,6 +243,142 @@ if (totalChanges > 500) { ## ๐Ÿงช Testing Your Rule +### How to Test Your Changes + +There are two main approaches to test your rule changes in a real GitHub environment before merging: + +#### Option 1: Testing via Branch (Same Repository) + +If you have write access to the repository, you can test directly using a feature branch: + +**Step 1:** Push your changes to a feature branch +```bash +git checkout -b feat/my-new-rule +git add src/rules/my-new-rule.js __tests__/my-new-rule.test.js +git commit -m "feat: add my new rule" +git push origin feat/my-new-rule +``` + +**Step 2:** Update the workflow in a test repository to use your branch +```yaml +# In your test repository's .github/workflows/pr-labeler.yml +jobs: + label: + uses: workflow-kit/pr-auto-labeler/.github/workflows/pr-auto-labeler.yml@feat/my-new-rule # Use your branch + with: + enabled_rules: '["my-new-rule"]' + enable_debug: true # Enable debug mode to see logs +``` + +**Step 3:** Create a test PR in your test repository +- Make changes that should trigger your rule +- Check the GitHub Actions logs to verify the rule works +- Verify the correct labels are applied + +**Step 4:** Iterate if needed +```bash +# Make changes to your rule +git add -A +git commit -m "fix: improve rule detection" +git push origin feat/my-new-rule +# Create another test PR to verify the changes +``` + +--- + +#### Option 2: Testing via Fork + +If you're contributing from a fork (most common for external contributors): + +**Step 1:** Fork the repository and clone your fork +```bash +git clone https://github.com/YOUR-USERNAME/pr-auto-labeler.git +cd pr-auto-labeler +``` + +**Step 2:** Create your feature branch and make changes +```bash +git checkout -b feat/my-new-rule +# Add your rule file +# Add tests +git add -A +git commit -m "feat: add my new rule" +git push origin feat/my-new-rule +``` + +**Step 3:** Set up a test repository to use your fork +In your test repository, create `.github/workflows/pr-labeler.yml`: + +```yaml +name: Test My New Rule + +on: + pull_request: + types: [opened, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + +jobs: + label: + # Point to YOUR fork and branch + uses: YOUR-USERNAME/pr-auto-labeler/.github/workflows/pr-auto-labeler.yml@feat/my-new-rule + with: + enabled_rules: '["my-new-rule"]' + enable_debug: true # Important: see what's happening +``` + +**Step 4:** Create test PRs in your test repository +- Make changes that should trigger your rule +- Check the Actions tab to see workflow execution +- Verify labels are applied correctly + +**Step 5:** Iterate and refine +```bash +# Make improvements to your rule +git add -A +git commit -m "fix: handle edge case" +git push origin feat/my-new-rule +# The next test PR will use the updated code +``` + +**Step 6:** Submit your PR to the main repository +Once satisfied with testing: +```bash +# Create a PR from your fork to workflow-kit/pr-auto-labeler +# GitHub will show you the "Contribute" button +``` + +--- + +### Testing Tips + +**โœ… Enable Debug Mode**: Always use `enable_debug: true` when testing +```yaml +with: + enabled_rules: '["my-rule"]' + enable_debug: true # Shows detailed execution logs +``` + +**โœ… Test Multiple Scenarios**: Create test PRs with different file combinations +- Positive case: Files that should trigger the rule +- Negative case: Files that should NOT trigger the rule +- Edge cases: Empty files, special characters, large files + +**โœ… Check GitHub Actions Logs**: +1. Go to the "Actions" tab in your test repository +2. Click on the latest workflow run +3. Expand the logs to see debug output +4. Look for your rule's debug messages + +**โœ… Verify Labels**: +- Check the PR's label section +- Ensure only expected labels are applied +- Test label overrides if using custom names + +--- + ### Automated Testing with Jest We use Jest for unit testing. Before submitting your rule, add tests for it: diff --git a/README.md b/README.md index 6714292..2cb4ce8 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@ # ๐Ÿท๏ธ PR Auto-Labeler -> **Automatically label your pull requests** based on code changes. Set up in 2 minutes. +> **Automatically label your pull requests** based on code changes, patterns, and metadata. Set up in 2 minutes. [![GitHub](https://img.shields.io/badge/GitHub-workflow--kit%2Fpr--auto--labeler-blue?logo=github)](https://github.com/workflow-kit/pr-auto-labeler) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) +[![Coverage](https://img.shields.io/badge/coverage-80%25+-brightgreen)](https://github.com/workflow-kit/pr-auto-labeler) --- @@ -29,133 +30,438 @@ jobs: uses: workflow-kit/pr-auto-labeler/.github/workflows/pr-auto-labeler.yml@v0.0.1 with: # โš ๏ธ IMPORTANT: Enable the rules you want (all disabled by default) - enabled_rules: '["ui-change", "env-change", "potential-secret-leak"]' + enabled_rules: '["ui-change", "env-change", "potential-secret-leak", "large-pr", "test-missing"]' ``` -### Available Rules +### Step 2: Commit & Push -Choose which rules to enable from the table below: +```bash +git add .github/workflows/pr-labeler.yml +git commit -m "Add PR auto-labeler" +git push +``` -| Rule Name | Label | Detects | File Types | Use Case | -|-----------|-------|---------|------------|----------| -| `ui-change` | `ui-change` ๐ŸŸข | Frontend files | `.html`, `.css`, `.scss`, `.jsx`, `.tsx`, `.vue` | Track UI changes | -| `style-change` | `style-change` ๐ŸŸฃ | Style-only changes | `.css`, `.scss` (no JS/TS) | Identify cosmetic changes | -| `env-change` | `env-change` ๐ŸŸ  | Environment files | `.env`, `.env.*`, `config.yml`, `config.json` | Track config changes | -| `new-env-variable` | `new-env-variable` ๐ŸŸก | New env variables | Detects new `KEY=value` in diffs | Flag new config | -| `potential-secret-leak` | `potential-secret-leak` ๐Ÿ”ด | Secrets detected | Keywords: `API_KEY`, `PASSWORD`, `SECRET`, `TOKEN` | Security review | -| `docker-change` | `docker-change` โšซ | Docker files | `Dockerfile`, `.dockerignore`, `docker-compose.yml` | Track Docker config | -| `migration` | `migration` ๐Ÿ”ต | Migration files | `migrations/**`, `db/migrations/**`, `database/migrations/**` | Track DB migrations | -| `risky-migration` | `risky-migration` ๐Ÿ”ด | Risky migrations | DROP, TRUNCATE, ALTER DROP in migration files | Flag dangerous operations | -| `schema-change` | `schema-change` ๐ŸŸก | Schema changes | ALTER, RENAME, MODIFY COLUMN in migration files | Track DB schema modifications | +### Step 3: Done! โœ… -**Example configurations:** -```yaml -# Enable all rules -enabled_rules: '["ui-change", "style-change", "env-change", "new-env-variable", "potential-secret-leak", "docker-change"]' +Create a pull request and labels will be applied automatically based on your enabled rules. + +--- + +## ๐Ÿ“‹ Available Rules -# Frontend team only +Choose which rules to enable from the comprehensive list below. **All rules are disabled by default** - you must explicitly enable the ones you want. + +### ๐ŸŽจ Frontend & UI Rules + +| Rule Name | Label | Detects | Use Case | +|-----------|-------|---------|----------| +| `ui-change` | ๐ŸŸข `ui-change` | Frontend component files (`.jsx`, `.tsx`, `.vue`, `.html`) | Track UI/component changes | +| `style-change` | ๐ŸŸฃ `style-change` | Style-only changes (`.css`, `.scss`, `.sass` without JS) | Identify cosmetic-only changes | + +**Example:** +```yaml enabled_rules: '["ui-change", "style-change"]' +``` -# Security-focused -enabled_rules: '["potential-secret-leak"]' +--- + +### ๐Ÿ—„๏ธ Database Rules + +| Rule Name | Label | Detects | Use Case | +|-----------|-------|---------|----------| +| `migration` | ๐Ÿ”ต `migration` | Migration files in `migrations/`, `db/migrations/` | Track all DB migrations | +| `risky-migration` | ๐Ÿ”ด `risky-migration` | Dangerous SQL operations (DROP, TRUNCATE, ALTER DROP) | Flag high-risk migrations | +| `schema-change` | ๐ŸŸก `schema-change` | Schema modifications (ALTER, RENAME, MODIFY COLUMN) | Track schema changes | +| `safe-migration` | ๐ŸŸข `safe-migration` | Safe additive migrations (CREATE, INSERT, ADD COLUMN) | Identify low-risk migrations | -# Infrastructure team -enabled_rules: '["docker-change", "env-change"]' +**Example:** +```yaml +enabled_rules: '["migration", "risky-migration", "safe-migration"]' ``` -### Step 2: Commit & Push +--- -```bash -git add .github/workflows/pr-labeler.yml -git commit -m "Add PR auto-labeler" -git push +### ๐Ÿ”ง Environment & Configuration Rules + +| Rule Name | Label | Detects | Use Case | +|-----------|-------|---------|----------| +| `env-change` | ๐ŸŸ  `env-change` | Environment files (`.env`, `config.yml`, `config.json`) | Track configuration changes | +| `new-env-variable` | ๐ŸŸก `new-env-variable` | New environment variables added in diffs | Flag new configuration | +| `potential-secret-leak` | ๐Ÿ”ด `potential-secret-leak` | Keywords: `API_KEY`, `PASSWORD`, `SECRET`, `TOKEN` | Security review required | + +**Example:** +```yaml +enabled_rules: '["env-change", "new-env-variable", "potential-secret-leak"]' ``` -### Step 3: Done! โœ… +--- -Create a pull request and labels will be applied automatically. +### ๐Ÿงช Testing Rules + +| Rule Name | Label | Detects | Use Case | +|-----------|-------|---------|----------| +| `test-only-change` | ๐ŸŸข `test-only-change` | Only test files modified, no source changes | Fast-track test improvements | +| `test-missing` | ๐Ÿ”ด `test-missing` | Source code changed without corresponding test changes | Require tests for code changes | +| `test-improvement` | ๐ŸŸก `test-improvement` | Tests added/improved with source changes | Acknowledge good testing practices | + +**Example:** +```yaml +enabled_rules: '["test-only-change", "test-missing", "test-improvement"]' +``` --- -## โš™๏ธ Configuration Options +### ๐Ÿ“ฆ Dependency Rules + +| Rule Name | Label | Detects | Use Case | +|-----------|-------|---------|----------| +| `dependency-change` | ๐ŸŸ  `dependency-change` | Changes to `package.json`, `requirements.txt`, `Gemfile`, etc. | Track dependency updates | +| `new-dependency` | ๐ŸŸก `new-dependency` | New dependencies added to project | Review new external dependencies | +| `dependency-downgrade` | ๐Ÿ”ด `dependency-downgrade` | Dependency versions downgraded | Flag potential security/compatibility issues | + +**Example:** +```yaml +enabled_rules: '["dependency-change", "new-dependency", "dependency-downgrade"]' +``` + +--- -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `enabled_rules` | JSON Array | `[]` | **Required:** Rules to enable (all disabled by default) | -| `label_overrides` | JSON Object | `{}` | **Optional:** Custom label names (e.g., `{"ui-change":"frontend"}`) | -| `enable_debug` | Boolean | `false` | **Optional:** Enable debug logging | +### ๐Ÿ”„ CI/CD & Infrastructure Rules -**Examples:** +| Rule Name | Label | Detects | Use Case | +|-----------|-------|---------|----------| +| `ci-change` | ๐Ÿ”ต `ci-change` | CI workflow changes (GitHub Actions, GitLab CI, CircleCI, Jenkins) | Track CI/CD modifications | +| `docker-change` | โšซ `docker-change` | Docker files (`Dockerfile`, `docker-compose.yml`, `.dockerignore`) | Track containerization changes | +| `infra-change` | ๐ŸŸฃ `infra-change` | Infrastructure configs (Terraform, Kubernetes, Helm, Ansible) | Track infrastructure as code | -Override label names: +**Example:** ```yaml -enabled_rules: '["ui-change"]' -label_overrides: '{"ui-change":"frontend"}' -# Will apply "frontend" label instead of "ui-change" +enabled_rules: '["ci-change", "docker-change", "infra-change"]' +``` + +--- + +### ๐Ÿ”’ Security Rules + +| Rule Name | Label | Detects | Use Case | +|-----------|-------|---------|----------| +| `security-change` | ๐Ÿ”ด `security-change` | Changes in security-sensitive areas (auth, crypto, JWT, OAuth) | Require security review | +| `risky-code` | ๐Ÿ”ด `risky-code` | Dangerous patterns (`eval`, `exec`, `dangerouslySetInnerHTML`) | Flag potentially unsafe code | + +**Example:** +```yaml +enabled_rules: '["security-change", "risky-code"]' +``` + +--- + +### ๐Ÿง  Code Semantics Rules + +| Rule Name | Label | Detects | Use Case | +|-----------|-------|---------|----------| +| `function-removed` | ๐Ÿ”ด `function-removed` | Functions or classes removed from codebase | Flag breaking changes | +| `new-feature` | ๐ŸŸข `new-feature` | New features added (new files, "feat:" commits) | Highlight feature additions | +| `non-functional-change` | โšช `non-functional-change` | Documentation/text-only changes (no code) | Fast-track doc updates | +| `refactor` | ๐ŸŸก `refactor` | Code refactoring or multiple file renames | Identify code cleanup | + +**Example:** +```yaml +enabled_rules: '["function-removed", "new-feature", "refactor"]' +``` + +--- + +### ๐Ÿ“Š PR Meta Rules + +| Rule Name | Label | Detects | Use Case | +|-----------|-------|---------|----------| +| `large-pr` | ๐Ÿ”ด `large-pr` | PRs with >500 lines changed | Flag PRs that need splitting | +| `missing-description` | ๐ŸŸก `missing-description` | PR description <30 characters | Require better PR descriptions | +| `no-linked-issue` | ๐ŸŸก `no-linked-issue` | No issue linked (`Closes #123`, `Fixes #456`) | Ensure issue tracking | +| `work-in-progress` | ๐ŸŸ  `work-in-progress` | Draft PRs or titles with "WIP", "DNM" | Flag incomplete work | + +**Example:** +```yaml +enabled_rules: '["large-pr", "missing-description", "no-linked-issue", "work-in-progress"]' +``` + +--- + +## ๐ŸŽฏ Common Configuration Examples + +### ๐Ÿข **Full-Stack Team** +```yaml +enabled_rules: '[ + "ui-change", "style-change", + "test-missing", "test-improvement", + "dependency-change", "new-dependency", + "large-pr", "missing-description" +]' +``` + +### ๐Ÿ”’ **Security-Focused** +```yaml +enabled_rules: '[ + "potential-secret-leak", + "security-change", + "risky-code", + "risky-migration", + "dependency-downgrade" +]' +``` + +### ๐ŸŽจ **Frontend Team** +```yaml +enabled_rules: '[ + "ui-change", + "style-change", + "test-missing", + "dependency-change" +]' +``` + +### ๐Ÿ—„๏ธ **Backend/Database Team** +```yaml +enabled_rules: '[ + "migration", + "risky-migration", + "safe-migration", + "test-missing", + "new-dependency" +]' +``` + +### โš™๏ธ **DevOps/Platform Team** +```yaml +enabled_rules: '[ + "ci-change", + "docker-change", + "infra-change", + "env-change", + "security-change" +]' ``` -Enable debug mode: +### ๐Ÿ“ **Quality Enforcement** +```yaml +enabled_rules: '[ + "large-pr", + "test-missing", + "missing-description", + "no-linked-issue", + "risky-code" +]' +``` + +--- + +## โš™๏ธ Advanced Configuration + +### Custom Label Names + +Override default label names with your own: + +```yaml +enabled_rules: '["ui-change", "test-missing"]' +label_overrides: '{ + "ui-change": "frontend", + "test-missing": "needs-tests" +}' +# Will apply "frontend" and "needs-tests" labels instead +``` + +### Debug Mode + +Enable detailed logging to troubleshoot rule execution: + ```yaml enabled_rules: '["ui-change"]' enable_debug: true -# Shows detailed logs: files analyzed, rules executed, labels detected +# Shows: files analyzed, rules executed, patterns matched, labels applied +``` + +### Complete Configuration Example + +```yaml +name: Auto Label PRs + +on: + pull_request: + types: [opened, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + +jobs: + label: + uses: workflow-kit/pr-auto-labeler/.github/workflows/pr-auto-labeler.yml@v0.0.1 + with: + enabled_rules: '[ + "ui-change", + "test-missing", + "potential-secret-leak", + "large-pr", + "missing-description" + ]' + label_overrides: '{ + "ui-change": "frontend", + "test-missing": "needs-tests" + }' + enable_debug: false ``` --- +## ๐Ÿ“Š Configuration Options Reference + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `enabled_rules` | JSON Array | โœ… Yes | `[]` | List of rule names to enable | +| `label_overrides` | JSON Object | No | `{}` | Custom label name mappings | +| `enable_debug` | Boolean | No | `false` | Enable verbose debug logging | + +--- + ## ๐Ÿ› Troubleshooting -### Labels Not Applied? +### โŒ Labels Not Applied? -1. โœ… **Check if rules are enabled** - All rules are disabled by default! +1. **Check if rules are enabled** - All rules are disabled by default! ```yaml enabled_rules: '["ui-change"]' # Must not be empty! ``` -2. โœ… **Enable debug mode** to see what's happening: +2. **Enable debug mode** to see execution details: ```yaml enable_debug: true ``` -3. โœ… **Check workflow logs** for messages like: - - `โš ๏ธ No rules enabled` - - `โš ๏ธ No rules loaded` +3. **Check workflow logs** for messages: + - `โš ๏ธ No rules enabled` - Add rules to `enabled_rules` + - `โš ๏ธ No rules loaded` - Check rule names are correct + - `โœ… Applied labels: [...]` - Shows which labels were applied -### Workflow Not Running? +### โŒ Workflow Not Running? -1. โœ… Verify file is at `.github/workflows/pr-labeler.yml` -2. โœ… Check permissions are set correctly +1. โœ… Verify file location: `.github/workflows/pr-labeler.yml` +2. โœ… Check `permissions` block includes `pull-requests: write` 3. โœ… Ensure GitHub Actions is enabled in repository settings +4. โœ… Confirm PR trigger is set: `on: pull_request:` + +### โŒ Some Rules Not Working? + +1. โœ… Check rule name spelling in `enabled_rules` +2. โœ… Enable `enable_debug: true` to see which rules execute +3. โœ… Verify your changes match the rule's detection patterns +4. โœ… Check if `label_overrides` has typos --- -## ๐Ÿ“ Examples +## ๐Ÿ“ Real-World Examples -**Frontend Change:** -- PR modifies: `index.html`, `styles.css` -- Config: `enabled_rules: '["ui-change", "style-change"]'` -- Result: Gets `ui-change` and `style-change` labels +### Example 1: Frontend PR +**Changed files:** `src/components/Button.tsx`, `styles/button.css` -**Adding Secret:** -- PR adds: `.env` with `API_KEY=secret123` -- Config: `enabled_rules: '["env-change", "new-env-variable", "potential-secret-leak"]'` -- Result: Gets all three labels +**Config:** +```yaml +enabled_rules: '["ui-change", "style-change", "test-missing"]' +``` + +**Result:** Gets labels `ui-change`, `style-change`, and `test-missing` (if no test changes) + +--- + +### Example 2: Database Migration PR +**Changed files:** `db/migrations/20240101_add_users.sql` with `CREATE TABLE users` + +**Config:** +```yaml +enabled_rules: '["migration", "safe-migration", "risky-migration"]' +``` + +**Result:** Gets labels `migration` and `safe-migration` (CREATE is safe) + +--- + +### Example 3: Security Review PR +**Changed files:** `src/auth/login.ts`, added `eval(userInput)` + +**Config:** +```yaml +enabled_rules: '["security-change", "risky-code", "test-missing"]' +``` + +**Result:** Gets all three labels - requires security review! + +--- + +### Example 4: Large Refactoring PR +**Changed files:** 15 files, 800 lines changed, multiple renames + +**Config:** +```yaml +enabled_rules: '["large-pr", "refactor", "test-missing"]' +``` + +**Result:** Gets `large-pr` (>500 lines), `refactor` (many renames) + +--- + +## ๐ŸŽ“ Best Practices + +### โœ… **Start Small** +Begin with 3-5 essential rules, then expand: +```yaml +enabled_rules: '["large-pr", "test-missing", "potential-secret-leak"]' +``` + +### โœ… **Combine Related Rules** +Group rules by concern: +```yaml +# Security bundle +enabled_rules: '["security-change", "risky-code", "potential-secret-leak"]' +``` + +### โœ… **Use Custom Labels** +Match your team's existing label conventions: +```yaml +label_overrides: '{"ui-change": "area/frontend", "test-missing": "needs-tests"}' +``` + +### โœ… **Enable Debug for New Rules** +When adding new rules, debug first: +```yaml +enable_debug: true # Remove after verifying +``` --- ## ๐Ÿค Contributing -Want to add a new rule? See [CONTRIBUTING.md](CONTRIBUTING.md) for complete guide. +Want to add a new rule or improve existing ones? See [CONTRIBUTING.md](CONTRIBUTING.md) for: +- Rule development guide +- Testing requirements +- How to test locally +- Contribution workflow --- -## ๐Ÿ”— Links +## ๐Ÿ“š Documentation -- **๐Ÿ“– Documentation:** [docs/DESIGN.md](docs/DESIGN.md) -- **๐Ÿค Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) +- **๐Ÿ“– Design Philosophy:** [docs/DESIGN.md](docs/DESIGN.md) +- **๐Ÿค Contributing Guide:** [CONTRIBUTING.md](CONTRIBUTING.md) - **๐Ÿ’ฌ Discussions:** [GitHub Discussions](https://github.com/workflow-kit/pr-auto-labeler/discussions) -- **๐Ÿ› Issues:** [GitHub Issues](https://github.com/workflow-kit/pr-auto-labeler/issues) +- **๐Ÿ› Report Issues:** [GitHub Issues](https://github.com/workflow-kit/pr-auto-labeler/issues) --- -**Made with โค๏ธ by the community** +## ๐Ÿ“œ License + +MIT License - see [LICENSE](LICENSE) for details. + +--- + +**Made with โค๏ธ by the open-source community** + +โญ Star this repo if it helps your workflow!