docs: add standardized Homebrew documentation template and checklist#281
docs: add standardized Homebrew documentation template and checklist#281
Conversation
Create reusable templates for Homebrew formula documentation: 1. HOMEBREW_FORMULA_TEMPLATE.md: - Standard template for CONTRIBUTING.md sections - Standard template for CLAUDE.md sections - Customization guide with package name replacements - Examples for rxiv-maker, TaskRepo, folder2md4llms - Consistency checklist 2. HOMEBREW_DOCS_CHECKLIST.md: - Quick review checklist for CONTRIBUTING.md and CLAUDE.md - Common issues detection (hardcoded versions, absolute paths) - Repository-specific checks - Automated review patterns - Reference to related PRs Benefits: - Ensures consistency across HenriquesLab ecosystem - Provides clear guidance for new package additions - Facilitates automated review detection - Documents established patterns from PR #280, #37, #12 Template can be used for future packages and for reviewing existing documentation across the organization. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
PR Review: Homebrew Documentation Template and Checklist✅ Overall Assessment: Excellent WorkThis PR adds valuable standardized documentation templates that will significantly improve consistency across the HenriquesLab ecosystem. The templates are well-structured, comprehensive, and address real pain points identified in related PRs. 🎯 Strengths1. Clear Structure and Organization
2. Practical and Actionable
3. Addresses Real Issues
4. Consistency Focus
🔍 Code Quality ObservationsDocumentation Quality: ✅ Excellent
Template Design: ✅ Well-Designed
Maintainability: ✅ Good
💡 Suggestions for Improvement1. Consider Adding Version Number to ChecklistIn # Additional pattern to detect version references in documentation
grep -n "v[0-9]\+\.[0-9]\+\.[0-9]\+" CONTRIBUTING.md | grep -v "X.Y.Z"This would catch any missed hardcoded version numbers. 2. Link Between DocumentsConsider adding a cross-reference at the top of each document: In > 📋 **Template**: See [HOMEBREW_FORMULA_TEMPLATE.md](./HOMEBREW_FORMULA_TEMPLATE.md) for the standard templateIn > ✅ **Checklist**: Use [HOMEBREW_DOCS_CHECKLIST.md](./HOMEBREW_DOCS_CHECKLIST.md) to verify your documentation3. Testing Automation SuggestionThe grep patterns in the checklist could be packaged into a simple validation script: #!/bin/bash
# scripts/validate-homebrew-docs.sh
# Run automated checks from HOMEBREW_DOCS_CHECKLIST.mdThis is optional but would make the checklist even more actionable. 4. Minor: TaskRepo Package Name InconsistencyIn the template (line 141 and 161), you reference 🔒 Security Considerations✅ No Security Concerns
🧪 Test Coverage✅ Appropriate for Documentation
Recommendation: After merge, manually test the template with one new repository to validate the workflow end-to-end. ⚡ Performance Considerations✅ Not Applicable
📋 Alignment with CLAUDE.md✅ Excellent AlignmentThis PR directly supports the automation goals outlined in CLAUDE.md:
The templates align perfectly with the "Homebrew Formula Management" section in CLAUDE.md and will help Claude proactively maintain formula updates. 🎯 Recommendation: APPROVE ✅This PR is ready to merge with only minor optional improvements suggested above. The templates are well-crafted, practical, and will provide significant value across the HenriquesLab ecosystem. Before Merging:
After Merging:
Great work on improving documentation consistency across the ecosystem! 🎉 Review generated with reference to CLAUDE.md coding standards and best practices. |
There was a problem hiding this comment.
Pull request overview
Adds standardized, reusable documentation templates and a review checklist for Homebrew formula update docs to keep Homebrew-related guidance consistent across HenriquesLab repositories.
Changes:
- Introduces a full Homebrew formula update documentation template for CONTRIBUTING.md and CLAUDE.md.
- Adds a review checklist with common pitfalls and grep-based indicators for automated review.
- Provides customization guidance and examples for known packages.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/HOMEBREW_FORMULA_TEMPLATE.md | Adds a standardized template for documenting automated/manual Homebrew formula update workflows. |
| docs/HOMEBREW_DOCS_CHECKLIST.md | Adds a checklist and common-issue detection patterns to review Homebrew documentation consistency. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - **TaskRepo** → CLI: `tsk` | ||
| - **folder2md4llms** → CLI: `folder2md` | ||
|
|
||
| ### Verification Commands | ||
| Check if package-specific verification is included where applicable: | ||
| - rxiv-maker: `rxiv check-installation` (optional) | ||
| - TaskRepo: `tsk --version` |
There was a problem hiding this comment.
In the “Package Names” section, TaskRepo is a repository name, but elsewhere (including the template examples) the placeholder refers to the PyPI/formula name (taskrepo). Using “TaskRepo” here makes the mapping ambiguous; consider listing the actual package/formula name (taskrepo) to match Homebrew/PyPI usage and the template’s replacement guidance.
| - **TaskRepo** → CLI: `tsk` | |
| - **folder2md4llms** → CLI: `folder2md` | |
| ### Verification Commands | |
| Check if package-specific verification is included where applicable: | |
| - rxiv-maker: `rxiv check-installation` (optional) | |
| - TaskRepo: `tsk --version` | |
| - **taskrepo** → CLI: `tsk` | |
| - **folder2md4llms** → CLI: `folder2md` | |
| ### Verification Commands | |
| Check if package-specific verification is included where applicable: | |
| - rxiv-maker: `rxiv check-installation` (optional) | |
| - taskrepo: `tsk --version` |
| # Pattern detection for automated reviews | ||
| grep -n "VERSION=[0-9]" CONTRIBUTING.md # Hardcoded version | ||
| grep -n "~/GitHub/homebrew" CONTRIBUTING.md # Absolute path | ||
| grep -n "^### 1\." CONTRIBUTING.md # Manual-first approach (missing automated section) |
There was a problem hiding this comment.
The automated review indicator grep -n "^### 1\." CONTRIBUTING.md is not specific to Homebrew sections and may flag unrelated headings, creating false positives. Consider matching a more specific pattern (e.g., the Homebrew section header plus a manual step heading, or searching for the absence of an “Automated Workflow” heading).
| grep -n "^### 1\." CONTRIBUTING.md # Manual-first approach (missing automated section) | |
| grep -n "^### 1\. Get Package Information from PyPI" CONTRIBUTING.md # Manual-first Homebrew section (missing automated section) |
| ## Related PRs | ||
|
|
||
| Template established and applied in: | ||
| - **rxiv-maker**: PR #280 | ||
| - **folder2md4llms**: PR #37 | ||
| - **TaskRepo**: PR #12 | ||
|
|
There was a problem hiding this comment.
This file references “folder2md4llms PR #37” as the source of the established Homebrew template patterns, but the referenced PR summary in this PR’s metadata appears unrelated to Homebrew documentation. To avoid confusion, consider either linking to the specific Homebrew-docs PR/commit in that repository or removing the PR number reference here.
| - New utility commands are added to homebrew-formulas | ||
| - Common issues or best practices are identified | ||
|
|
||
| **Last updated:** 2026-02-02 (aligned with rxiv-maker PR #280, folder2md4llms PR #37, TaskRepo PR #12) |
There was a problem hiding this comment.
The “Last updated” note claims alignment with “folder2md4llms PR #37”, but the referenced PR summary in this PR’s metadata appears unrelated to Homebrew documentation. Consider updating this reference to the correct PR/commit (or removing the PR number) so readers can trace the relevant change history accurately.
Code reviewNo issues found. Checked for bugs and template completeness. This PR adds excellent standardization resources: HOMEBREW_FORMULA_TEMPLATE.md:
HOMEBREW_DOCS_CHECKLIST.md:
Both documents are well-structured, comprehensive, and will ensure consistency across the HenriquesLab ecosystem for future packages. The templates accurately reflect the patterns established in the three related PRs. 🤖 Generated with Claude Code - If this code review was useful, please react with 👍. Otherwise, react with 👎. |
This patch release focuses on documentation improvements and security compliance: Documentation: - Align Homebrew formula workflow with CLAUDE.md automation (#280) - Add standardized Homebrew documentation templates (#281) - Prioritize just-based automation across ecosystem Security: - Remove private repository references from public docs (#282) - Comply with CLAUDE.md security guidelines Affects: CONTRIBUTING.md, README.md, CHANGELOG.md, docs/ECOSYSTEM.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This patch release focuses on documentation improvements and security compliance: Documentation: - Align Homebrew formula workflow with CLAUDE.md automation (#280) - Add standardized Homebrew documentation templates (#281) - Prioritize just-based automation across ecosystem Security: - Remove private repository references from public docs (#282) - Comply with CLAUDE.md security guidelines Affects: CONTRIBUTING.md, README.md, CHANGELOG.md, docs/ECOSYSTEM.md Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
1 participant
Summary
This PR adds reusable templates and checklists for Homebrew formula documentation to ensure consistency across all HenriquesLab repositories.
Related to:
New Documentation
1. ✅ HOMEBREW_FORMULA_TEMPLATE.md
Comprehensive template for Homebrew documentation:
Contents:
Template features:
just releaseworkflow (recommended)../homebrew-formulas)2. ✅ HOMEBREW_DOCS_CHECKLIST.md
Quick reference checklist for reviews:
Contents:
Issue detection examples:
Use Cases
For New Packages
For Documentation Reviews
For AI Assistants
Benefits
Testing
Repository Coverage
Templates can be applied to all HenriquesLab packages with Homebrew formulas:
References