Add Watchflow governance rules (3 rules, 2 high-priority)

[dkargatzis]

Add Watchflow Governance Rules

This PR adds automated governance rules for warestack/watchflow based on repository analysis of recent PR history and codebase patterns.

Repository Health Analysis Report: warestack/watchflow

This report evaluates the current health of the warestack/watchflow repository based on key hygiene metrics. The goal is to identify actionable problems and provide recommendations to improve governance and maintainability.

Metric	Value	Severity	Category	Explanation
Unlinked Issue Rate	30.0%	High	Issue Management	A high percentage of PRs are not linked to issues, reducing traceability and accountability.
Average PR Size	211 lines	Medium	Code Review	PR size is moderate but approaching the upper limit for reviewability; large PRs hinder effective reviews.
First-Time Contributors	0	Low	Community	No new contributors, indicating potential barriers to entry or lack of outreach.
CI Skip Rate	0.0%	Low	CI/CD	No workflows are bypassed, indicating good CI/CD discipline.
Codeowner Bypass Rate	0.0%	Low	Code Review	No reviews bypassed codeowners, ensuring proper review governance.
New Code Test Coverage	10.3%	High	Testing	Very low test coverage on new code, increasing risk of defects and regressions.
Issue-Diff Mismatch Rate	0.0%	Low	Issue Management	No mismatch between issue descriptions and code changes, indicating good alignment.
Ghost Contributor Rate	0.0%	Low	Code Review	All contributors engage in reviews, indicating good collaboration.
AI Generated Rate	0.0%	Low	Code Quality	No low-signal AI-generated PRs detected.

Key Findings and Recommendations

1. Improve Issue Linking

• Problem: 30% of PRs are not linked to issues, which can cause loss of context and tracking difficulties.
• Recommendation: Implement a governance rule requiring PRs to reference an existing issue or create a new one before merging. Use automated checks to enforce this.

2. Manage PR Size

• Problem: Average PR size is 211 lines, nearing the 500-line threshold for unreviewability.
• Recommendation: Encourage smaller, incremental PRs through contribution guidelines and automated warnings for large PRs.

3. Increase Test Coverage

• Problem: New code has only 10.3% test coverage, posing a risk to code quality and stability.
• Recommendation: Establish minimum test coverage thresholds for new code and integrate coverage checks into CI pipelines. Provide guidelines and support for writing tests.

4. Encourage New Contributors

• Problem: No first-time contributors detected, which may limit community growth.
• Recommendation: Create onboarding documentation, label good first issues, and promote community engagement to attract new contributors.

Conclusion

The warestack/watchflow repository demonstrates strong CI/CD discipline and review governance but faces challenges in issue linking, test coverage, and community growth. Addressing these areas with clear governance policies and automation will enhance maintainability and collaboration.

Recommended Rules

Require PRs to include a reference to an existing issue by enforcing required labels or title patterns that include issue numbers. - High

Rationale: The rule mandating PRs to reference existing issues directly addresses the high unlinked issue rate (30%), improving traceability and accountability by ensuring all PRs are contextually linked to tracked issues, thereby enhancing issue management and repository governance.

Enforce a maximum file size or diff size limit to keep PRs manageable and reviewable. - Medium

Rationale: The rule enforcing a maximum file size and diff size limit directly addresses the medium-severity problem of large PRs (average 211 lines) by keeping changes manageable and easier to review, thereby improving code review effectiveness and maintainability.

Require PRs to include related tests and enforce presence of test files or test-related changes in the diff. - High

Rationale: The rule mandating PRs to include related tests directly addresses the high severity issue of very low new code test coverage (10.3%), mitigating risks of defects and regressions by ensuring new contributions are adequately tested.

Changes

• Adds .watchflow/rules.yaml with the recommended governance rules

Next Steps

1. Review the rules in .watchflow/rules.yaml
2. Adjust parameters if needed
3. Install the Watchflow GitHub App to enable automated enforcement
4. Merge this PR to activate the rules

---

Generated by Watchflow repository analysis.

Summary by CodeRabbit

• Chores
  • Updated pull request guidelines with streamlined rules. PRs now require issue references, must stay within file size limits (5 MB max), and include related test changes. Removed legacy approval and direct-push restrictions.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The .watchflow/rules.yaml file replaces a five-rule set with three new PR-focused rules. Removed rules include descriptive PR titles, contributor approval, tests required, code-owner checks, and direct push prevention. Added rules enforce issue-link requirements, file/diff size limits, and test file presence in PRs.

Changes

Cohort / File(s)	Summary
Workflow Rule Configuration .watchflow/rules.yaml	Replaced five existing "Essential Open Source Rules" with three new PR-focused rules: issue-linked PR requirement with label/title pattern enforcement, maximum file and diff size limits (5 MB and 500 chars respectively), and mandatory test file presence in PRs.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 Our rules grow lean, from five down to three,
Each PR now linked to issues, as they should be,
No mammoth diffs shall pass our watchful gate,
And tests must dance along—that is our fate! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: adding three Watchflow governance rules with priorities, directly matching the file modification in .watchflow/rules.yaml.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch watchflow/rules

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f5a3be1 and 548b423.

📒 Files selected for processing (1)

• .watchflow/rules.yaml

🔇 Additional comments (3)

.watchflow/rules.yaml (3)

30-34: Fix the malformed related_tests configuration; required_field_in_diff only supports substring matching, not regex patterns.

The current configuration at lines 30-34 is incorrectly structured. The required_field_in_diff validator only performs plain substring matching on diff additions (e.g., if all(text in additions for text in required_text)) and does not support regex patterns. Additionally, your suggestion to use regex patterns like (^|/)tests?/ would need the diff_pattern validator instead, which supports require_patterns with regex.

To properly enforce test file presence, use the related_tests validator with source_patterns and test_patterns parameters, or use diff_pattern with regex require_patterns to detect test-related changes in the diff. The generic tokens test, spec, coverage will indeed match non-test text if you continue using substring matching; restructure the rule to use one of the appropriate validators for your use case.

Likely an incorrect or invalid review comment.

---

2-12: Keep the title_pattern on one line for readability, but the current split is not technically broken.

The current multiline title_pattern on lines 11–12 works correctly. YAML's plain scalar parsing automatically converts the line break and indentation into a single space, so the resulting regex string is identical to keeping it on one line. While the suggested single-line format is clearer, the current format does not prevent regex matching.

Likely an incorrect or invalid review comment.

---

21-22: Remove unused diff_pattern configuration parameter.

The diff_pattern: ^.{0,500}$ parameter on line 22 is dead code—it's never consumed by any validator. MaxFileSizeCondition only accepts max_file_size_mb and ignores extra parameters; DiffPatternCondition (a separate validator) expects require_patterns, forbidden_patterns, and file_patterns, not diff_pattern. Delete this line to reduce configuration clutter.

Likely an incorrect or invalid review comment.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

Tip

🧪 Unit Test Generation v2 is now available!

We have significantly improved our unit test generation capabilities.

To enable: Add this to your .coderabbit.yaml configuration:

reviews:
  finishing_touches:
    unit_tests:
      enabled: true

Try it out by using the @coderabbitai generate unit tests command on your code files or under ✨ Finishing Touches on the walkthrough!

Have feedback? Share your thoughts on our Discord thread!

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}