docs: align Homebrew formula workflow with CLAUDE.md automation #280

paxcalpt · 2026-02-02T10:33:05Z

Summary

This PR addresses the automated review feedback from PR #279, which identified conflicts between the manual Homebrew formula update workflow in CONTRIBUTING.md and the automated just-based workflow documented in CLAUDE.md.

Fixes identified in post-merge review of PR #279:

Changes Made

1. ✅ Prioritize Automated Workflow

Added just release rxiv-maker as the recommended method
Restructured to show automated workflow first
Kept manual workflow as alternative for contributors without just installed
Added context about the homebrew-formulas repository utilities

2. ✅ Fix Hardcoded Version Placeholder

Changed VERSION=1.18.4 → VERSION=X.Y.Z to avoid confusion
Makes it clear this is a placeholder, not a specific version

3. ✅ Update Path References

Changed ~/GitHub/homebrew-formulas → ../homebrew-formulas (relative path)
Consistent with CLAUDE.md documentation
Removed assumption about user's directory structure

4. ✅ Add Automation Context

Documented available just utility commands:
- just list - List all formulas
- just check-updates - Check for PyPI updates
- just sha256 - Get SHA256 for specific version
Added link to homebrew-formulas repository

5. ✅ Restore Verification Command

Added rxiv check-installation back to README.md macOS section
Marked as optional verification step for LaTeX dependencies
While Homebrew handles dependencies automatically, this command helps verify LaTeX configuration

Testing

✅ All linting checks pass (nox -s lint)
✅ Documentation-only changes (no code modifications)
✅ Pre-commit hooks pass

Related Issues

Addresses automated review feedback from #279 (already merged)

Workflow Alignment

This PR ensures consistency between:

CONTRIBUTING.md - Contributor-facing documentation
CLAUDE.md - AI assistant and automation guidelines
homebrew-formulas repository - Formula management automation

Both workflows (automated and manual) are now documented, with automation clearly marked as recommended.

Address PR review feedback: 1. Prioritize automated workflow - Add 'just release rxiv-maker' as recommended method - Keep manual workflow as alternative for when just is unavailable - Reference homebrew-formulas repository utilities 2. Fix hardcoded version placeholder - Change VERSION=1.18.4 to VERSION=X.Y.Z for clarity 3. Update path references - Use relative path ../homebrew-formulas (consistent with CLAUDE.md) - Remove hardcoded ~/GitHub/homebrew-formulas assumption 4. Add automation context - Document just utility commands (list, check-updates, sha256) - Link to homebrew-formulas repository for full documentation 5. Restore verification command - Add rxiv check-installation to README macOS section - Mark as optional verification step for LaTeX dependencies Resolves conflicts with CLAUDE.md automation strategy while maintaining manual workflow documentation for contributors without just installed. Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

github-actions · 2026-02-02T10:34:27Z

Pull Request Review

✅ Overall Assessment

This PR successfully addresses the workflow alignment issues identified in PR #279. The changes are well-structured, clear, and properly prioritize the automated workflow while maintaining the manual option for contributors without just installed.

Strengths

1. ✅ Excellent Workflow Prioritization

Automated workflow (just release) is now clearly marked as "Recommended"
Manual workflow properly labeled as "Alternative"
Clear separation between the two approaches prevents confusion

2. ✅ Fixed Version Placeholder

Changed VERSION=1.18.4 → VERSION=X.Y.Z
This avoids the risk of contributors copying an outdated version number

3. ✅ Consistent Path References

Using ../homebrew-formulas (relative path) aligns perfectly with CLAUDE.md
Removes assumptions about user directory structure (~/GitHub/)

4. ✅ Enhanced Documentation Context

Added link to homebrew-formulas repository
Documented utility commands (just list, just check-updates, just sha256)
Clear explanation of what the automated workflow does

5. ✅ README.md Improvement

Restored rxiv check-installation as optional verification
Properly labeled as "optional" to avoid confusion
Helpful for users who want to verify LaTeX configuration

Code Quality & Best Practices

✅ Documentation Quality

Clear, concise language throughout
Proper use of markdown formatting
Logical structure with numbered sections
Good use of code blocks for commands

✅ Consistency

Aligns perfectly with CLAUDE.md guidelines
Maintains consistent tone and style with existing documentation
Path references match the project's conventions

✅ User Experience

Progressive disclosure: shows simple automated workflow first
Fallback option available for users without just
Clear explanations of what each step does

Potential Considerations

💡 Minor Enhancement Opportunities

Command Availability Check (Optional)
Consider adding a note about checking if just is available:
```
# Check if just is installed
which just || echo "Install just: brew install just"
```
This could help contributors quickly determine which workflow to use.
Link to homebrew-formulas justfile (Optional)
The PR mentions utility commands but could optionally link directly to the justfile for curious contributors who want to see the implementation.
Testing Section Consistency
Both workflows test the formula, but the automated workflow's testing is implicit. This is fine, but could be mentioned explicitly in the explanation (you do mention it in the list of what it does automatically).

Security, Performance & Test Coverage

✅ Security

No security concerns (documentation-only changes)
No hardcoded credentials or sensitive information

✅ Performance

Documentation changes have no performance impact

✅ Test Coverage

Appropriate for documentation-only PR
Linting checks passing as mentioned in PR description
Pre-commit hooks passing

Alignment with Project Standards

✅ CLAUDE.md Compliance

The changes align perfectly with CLAUDE.md sections:

Homebrew Formula Management (lines 401-461)
Uses ../homebrew-formulas relative path
Prioritizes just release rxiv-maker automated workflow
Documents all utility commands mentioned in CLAUDE.md

✅ Following Project Conventions

Uses proper markdown formatting per project style
Maintains existing documentation structure
Clear section headers and organization

Recommendations

✅ Ready to Merge

This PR is well-executed and ready to merge as-is. The changes are:

Clear and accurate
Consistent with project guidelines
Well-documented and user-friendly
Addresses all feedback from PR docs: update installation to single-command Homebrew and add formula update guide #279

Optional Follow-up (Low Priority)

If you want to further enhance the documentation in a future PR:

Add a troubleshooting section for common Homebrew formula update issues
Consider adding a flowchart or decision tree for workflow selection
Document what to do if just release fails mid-workflow

Summary

Verdict: ✅ APPROVED

This is a high-quality documentation improvement that:

Resolves the workflow inconsistency identified in docs: update installation to single-command Homebrew and add formula update guide #279
Improves contributor experience with clear guidance
Maintains proper fallback options for all contributors
Aligns perfectly with CLAUDE.md and project standards

Great work addressing the automated review feedback! The documentation is now consistent, clear, and properly guides contributors through both automated and manual workflows.

Suggested commit merge message:

docs: align Homebrew formula workflow with CLAUDE.md automation

- Prioritize just release workflow as recommended method
- Fix version placeholder (1.18.4 → X.Y.Z)
- Update path references to use relative paths
- Add automation utility commands documentation
- Restore optional check-installation verification in README

Addresses automated review feedback from PR #279

Copilot

Pull request overview

Aligns contributor and user documentation for maintaining the Homebrew formula with the automated just-based workflow referenced in CLAUDE.md, while keeping a manual fallback path.

Changes:

Adds an “Automated Workflow (Recommended)” section for Homebrew formula updates using just release rxiv-maker.
Reworks the manual Homebrew formula update steps (placeholder version, relative paths, clarified edit location).
Restores an optional rxiv check-installation verification step in the macOS README section.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
README.md	Adds optional macOS post-install verification command for LaTeX/dependency sanity-check.
CONTRIBUTING.md	Restructures Homebrew formula update guide to recommend `just` automation and clarifies manual update steps.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-02T10:36:50Z

README.md

+rxiv check-installation  # Verify LaTeX and dependencies
+```
+
 **Benefits:** Simple one-command installation, automatic dependency management (Python 3.13, LaTeX, git, gh), easy updates


The macOS “Benefits” line hardcodes Python 3.13, but the Linux/WSL section below documents Python 3.11+. This version-specific claim is likely to drift as the Homebrew formula updates; consider wording this as “Python 3.11+” or just “Python” to keep the README consistent and future-proof.

Suggested change

**Benefits:** Simple one-command installation, automatic dependency management (Python 3.13, LaTeX, git, gh), easy updates

**Benefits:** Simple one-command installation, automatic dependency management (Python 3.11+, LaTeX, git, gh), easy updates

Copilot · 2026-02-02T10:36:50Z

CONTRIBUTING.md


-### 1. Get Package Information from PyPI
+### Automated Workflow (Recommended)



Both workflows assume a local checkout of homebrew-formulas exists at ../homebrew-formulas relative to the rxiv-maker repo. Add a short prerequisite (e.g., clone location or adjust the path) so the instructions work for contributors whose repo layout differs.

Suggested change

Prerequisite: ensure you have a local clone of `homebrew-formulas` at `../homebrew-formulas` relative to your `rxiv-maker` checkout, or adjust the `cd` path below to match your setup.

Copilot · 2026-02-02T10:36:51Z

CONTRIBUTING.md

+VERSION=X.Y.Z  # Replace with new version
 curl "https://pypi.org/pypi/rxiv-maker/$VERSION/json" | \
  jq -r '.urls[] | select(.packagetype=="sdist") | "URL: \(.url)\nSHA256: \(.digests.sha256)"'


The manual workflow depends on jq, but the instructions don’t mention installing it. Please document jq as a prerequisite (or provide an alternative that doesn’t require it) so this step is runnable on a fresh machine.

Copilot · 2026-02-02T10:36:51Z

CONTRIBUTING.md

 rxiv --version
 ```

+**Note:** The automated workflow using `just` is preferred for consistency and efficiency. See the [homebrew-formulas repository](https://github.com/HenriquesLab/homebrew-formulas) for additional utility commands like `just list`, `just check-updates`, and `just sha256`


Add a trailing period at the end of this note (and consider wrapping the long line) to match the surrounding documentation style and avoid markdown-lint line-length violations if enforced.

Suggested change

**Note:** The automated workflow using `just` is preferred for consistency and efficiency. See the [homebrew-formulas repository](https://github.com/HenriquesLab/homebrew-formulas) for additional utility commands like `just list`, `just check-updates`, and `just sha256`

**Note:** The automated workflow using `just` is preferred for consistency and efficiency. See the

[homebrew-formulas repository](https://github.com/HenriquesLab/homebrew-formulas) for additional

utility commands like `just list`, `just check-updates`, and `just sha256`.

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 <[email protected]>

paxcalpt · 2026-02-02T10:57:33Z

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

…281) 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 <[email protected]>

* docs: add standardized Homebrew documentation template and checklist 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 <[email protected]> * security: remove private repository references from public docs Remove references to private website-rxiv-maker GitHub repository from public documentation, as per CLAUDE.md security guidelines. Changes: 1. CHANGELOG.md: - Replace GitHub repo link with deployed website URL - Remove website-rxiv-maker from ecosystem list 2. docs/ECOSYSTEM.md: - Update mermaid diagram node (website-rxiv-maker → Documentation Website) - Update repository table with deployed website URL - Update release workflow diagram - Update technical stats table All references now point to the public deployed website: https://rxiv-maker.henriqueslab.org Complies with CLAUDE.md line 338: "The website-rxiv-maker repository is **private** - do NOT reference it in public documentation" Security impact: Prevents exposure of private repository structure and internal development processes. Co-Authored-By: Claude Sonnet 4.5 <[email protected]> --------- Co-authored-by: Claude Sonnet 4.5 <[email protected]>

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 <[email protected]>

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 <[email protected]>

Copilot AI review requested due to automatic review settings February 2, 2026 10:33

Copilot started reviewing on behalf of paxcalpt February 2, 2026 10:33 View session

Copilot AI reviewed Feb 2, 2026

View reviewed changes

paxcalpt mentioned this pull request Feb 2, 2026

docs: align Homebrew formula workflow with CLAUDE.md automation HenriquesLab/folder2md4llms#37

Merged

paxcalpt mentioned this pull request Feb 2, 2026

docs: add standardized Homebrew documentation template and checklist #281

Merged

github-actions bot mentioned this pull request Feb 2, 2026

security: remove private repository references from public docs #282

Merged

paxcalpt merged commit b850c2c into main Feb 2, 2026
8 checks passed

paxcalpt mentioned this pull request Feb 2, 2026

Release v1.18.4 #283

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: align Homebrew formula workflow with CLAUDE.md automation #280

docs: align Homebrew formula workflow with CLAUDE.md automation #280

Uh oh!

paxcalpt commented Feb 2, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

paxcalpt commented Feb 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	Benefits: Simple one-command installation, automatic dependency management (Python 3.13, LaTeX, git, gh), easy updates
	Benefits: Simple one-command installation, automatic dependency management (Python 3.11+, LaTeX, git, gh), easy updates


		### 1. Get Package Information from PyPI
		### Automated Workflow (Recommended)



	Prerequisite: ensure you have a local clone of `homebrew-formulas` at `../homebrew-formulas` relative to your `rxiv-maker` checkout, or adjust the `cd` path below to match your setup.

docs: align Homebrew formula workflow with CLAUDE.md automation #280

docs: align Homebrew formula workflow with CLAUDE.md automation #280

Uh oh!

Conversation

paxcalpt commented Feb 2, 2026

Summary

Changes Made

1. ✅ Prioritize Automated Workflow

2. ✅ Fix Hardcoded Version Placeholder

3. ✅ Update Path References

4. ✅ Add Automation Context

5. ✅ Restore Verification Command

Testing

Related Issues

Workflow Alignment

Uh oh!

github-actions bot commented Feb 2, 2026

Pull Request Review

✅ Overall Assessment

Strengths

1. ✅ Excellent Workflow Prioritization

2. ✅ Fixed Version Placeholder

3. ✅ Consistent Path References

4. ✅ Enhanced Documentation Context

5. ✅ README.md Improvement

Code Quality & Best Practices

✅ Documentation Quality

✅ Consistency

✅ User Experience

Potential Considerations

💡 Minor Enhancement Opportunities

Security, Performance & Test Coverage

✅ Security

✅ Performance

✅ Test Coverage

Alignment with Project Standards

✅ CLAUDE.md Compliance

✅ Following Project Conventions

Recommendations

✅ Ready to Merge

Optional Follow-up (Low Priority)

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

paxcalpt commented Feb 2, 2026

Code review

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants