docs: update installation to single-command Homebrew and add formula update guide

[paxcalpt]

Summary

Updates documentation to feature single-command Homebrew installation and adds maintainer guide for updating the Homebrew formula.

Changes

• README.md: Simplify macOS installation to single command: brew install henriqueslab/formulas/rxiv-maker
• CONTRIBUTING.md: Add comprehensive Homebrew formula update instructions for maintainers

Benefits

• Simpler installation experience for macOS users (no need to tap first)
• Clear maintainer workflow for updating Homebrew formula
• Consistent with TaskRepo installation pattern

Testing

• Documentation updates only (no code changes)
• Installation command tested and verified

🤖 Generated with Claude Code

[github-actions]

PR Review: Documentation Updates for Homebrew Installation

Summary

This PR simplifies the macOS installation instructions and adds a manual Homebrew formula update guide. However, there are some important considerations regarding the formula update workflow.

---

✅ Positive Aspects

1. Simplified Installation Command: The single-command installation (brew install henriqueslab/formulas/rxiv-maker) is cleaner and more user-friendly than the two-step tap + install approach.

2. Clear Documentation Structure: The README changes are well-organized with proper emphasis on benefits and update commands.

3. No Code Changes: Documentation-only changes reduce risk of introducing bugs.

---

⚠️ Issues & Concerns

1. Discrepancy with CLAUDE.md Automation

The manual workflow added to CONTRIBUTING.md (lines 62-112) conflicts with the automated approach documented in CLAUDE.md (lines 401-462).

CLAUDE.md specifies:

• Homebrew formula updates should use just release rxiv-maker command
• The just workflow provides full automation: update → test → commit → push
• The homebrew-formulas repository has a justfile for this purpose

This PR adds:

• Manual curl/jq commands to fetch PyPI metadata
• Manual formula editing instructions
• Step-by-step manual testing workflow

Recommendation: Update CONTRIBUTING.md to reference the just-based workflow instead of manual steps, or at minimum provide both options with the automated approach marked as "(Recommended)".

2. Hardcoded Version in Example

VERSION=1.18.4  # Replace with new version

This hardcoded version (1.18.4) in CONTRIBUTING.md:69 may confuse maintainers. Consider using a placeholder like VERSION=X.Y.Z or VERSION=<new-version>.

3. Hardcoded Path Assumption

cd ~/GitHub/homebrew-formulas

CONTRIBUTING.md:83 assumes the repository is at ~/GitHub/homebrew-formulas. CLAUDE.md refers to it as ../homebrew-formulas (relative path). Consider using the relative path or noting this is an example path.

4. Missing Context on Automation Tools

The new section doesn't mention:

• That a justfile exists for automation
• The just list, just check-updates, just sha256 utility commands
• The simpler just release rxiv-maker one-command workflow

5. README: Removed Check Command

The PR removes rxiv check-installation from the macOS installation section. While Homebrew handles dependencies automatically, this command is still useful to verify LaTeX is properly configured. Consider keeping it as an optional verification step.

---

🔧 Suggested Improvements

Option A: Reference Automated Workflow (Recommended)

Replace the manual steps in CONTRIBUTING.md with:

## 🍺 Updating the Homebrew Formula

When releasing a new version, the Homebrew formula must be updated in the [`homebrew-formulas` repository](https://github.com/HenriquesLab/homebrew-formulas).

### Automated Workflow (Recommended)

```bash
cd ../homebrew-formulas
just release rxiv-maker  # Full workflow: update → test → commit → push

This automatically:

• Fetches the latest version from PyPI
• Downloads and calculates SHA256 checksum
• Updates the formula file
• Tests the installation
• Commits with standardized message
• Pushes to remote

Manual Workflow (Alternative)

If just is not available, see homebrew-formulas README for manual steps.

#### Option B: Provide Both Workflows

Keep the manual workflow but add the automated option first, clearly marked as recommended, with the manual steps as a fallback.

---

### 📋 **Testing Recommendations**

Since this is documentation-only:
- ✅ No code tests needed
- ✅ Verify installation command works: `brew install henriqueslab/formulas/rxiv-maker`
- ⚠️ Consider testing the manual workflow instructions on a clean system to ensure accuracy
- ⚠️ Verify the justfile commands exist in `../homebrew-formulas` repository

---

### 🎯 **Verdict**

**Status:** Changes requested

**Rationale:** While the README improvements are excellent, the CONTRIBUTING.md additions introduce a workflow that contradicts the project's documented automation strategy. Aligning with the `just`-based workflow in CLAUDE.md will provide maintainers with a more efficient and consistent release process.

**Recommendation:** Update the Homebrew formula section to reference the automated `just release` workflow, or clearly document both approaches with automation marked as preferred.

---

### 📚 **References**

- CLAUDE.md lines 401-462: Homebrew Formula Management
- homebrew-formulas repository: Should contain justfile with automation commands
- CLAUDE.md lines 434-461: Commands and workflow notes

---

*Generated by Claude Code - Review based on project's CLAUDE.md style guide and automation standards*

[Copilot]

Pull request overview

Updates user and maintainer documentation to streamline Homebrew installation and document the Homebrew formula update process.

Changes:

• Simplify macOS installation in README to a single fully-qualified brew install ... command.
• Add a maintainer-focused guide in CONTRIBUTING for updating/testing/auditing the Homebrew formula.

Reviewed changes

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

File	Description
README.md	Updates macOS Homebrew install/upgrade instructions and adds a “Benefits” note.
CONTRIBUTING.md	Adds step-by-step instructions for maintainers to update and validate the Homebrew formula.

---

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

[Copilot]

The new macOS section switches to the fully-qualified brew install henriqueslab/formulas/rxiv-maker, but there are still docs in this repo that instruct users to brew tap henriqueslab/formulas (e.g., docs/ECOSYSTEM.md:103). This will leave readers with conflicting Homebrew instructions—please update the other references in this repo to match the new single-command install flow (or link to a single canonical installation doc).

Suggested change

	brew install henriqueslab/formulas/rxiv-maker
	brew tap henriqueslab/formulas
	brew install rxiv-maker

[Copilot]

The Benefits line hard-codes specific dependencies/versions (e.g., “Python 3.13”, “gh”). Since the package itself only declares a minimum Python version (see pyproject.toml requires-python) and gh is an optional integration (not required for core usage), this statement is likely to become inaccurate. Suggest rephrasing to avoid pinning to a specific Python minor version and to clarify optional vs required tools.

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, LaTeX, git; optional GitHub CLI (gh) integration), easy updates

[Copilot]

Step 2 references editing homebrew-formulas/Formula/rxiv-maker.rb, but later steps assume you are already in the tap repo and use ./Formula/rxiv-maker.rb / git add Formula/rxiv-maker.rb. To avoid confusion, make the path consistent (e.g., refer to Formula/rxiv-maker.rb within the homebrew-formulas repo) and/or explicitly call out that this file lives in the separate HenriquesLab/homebrew-formulas repository.

Suggested change

	Edit `homebrew-formulas/Formula/rxiv-maker.rb`:
	In the `HenriquesLab/homebrew-formulas` tap repository, edit `Formula/rxiv-maker.rb`:

[Copilot]

The macOS install snippet no longer includes a post-install verification step (e.g., rxiv check-installation), while the Linux/WSL instructions still do. To keep the installation guidance consistent and to help users catch missing system dependencies early, consider adding the same verification command after the Homebrew install (even if the install itself is a single command).

Suggested change

	brew install henriqueslab/formulas/rxiv-maker
	brew install henriqueslab/formulas/rxiv-maker
	rxiv check-installation