From 96ff68f3ee7618cef3c83585ce3da4c745734d27 Mon Sep 17 00:00:00 2001 From: Ricardo Henriques Date: Mon, 2 Feb 2026 10:40:41 +0000 Subject: [PATCH] docs: align Homebrew workflow with automation and add CLAUDE.md Add automation guidelines and fix documentation inconsistencies: 1. Update CONTRIBUTING.md: - Add 'just release taskrepo' as recommended method - Keep manual workflow as alternative - Change VERSION=0.10.17 to VERSION=X.Y.Z - Change ~/GitHub/homebrew-formulas to ../homebrew-formulas - Add reference to homebrew-formulas repository utilities 2. Create CLAUDE.md: - Add comprehensive AI assistant guidelines - Document Homebrew formula automation workflow - Include development environment setup - Add release process documentation - Document code style and testing strategy 3. Update .gitignore: - Allow CLAUDE.md to be tracked (add !CLAUDE.md exception) Aligns with rxiv-maker PR #280 and folder2md4llms PR #37. Ensures consistency across HenriquesLab ecosystem. Co-Authored-By: Claude Sonnet 4.5 --- .gitignore | 1 + CLAUDE.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 46 +++++++++++++---- 3 files changed, 169 insertions(+), 10 deletions(-) create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index 7777e6b..3d76251 100644 --- a/.gitignore +++ b/.gitignore @@ -60,6 +60,7 @@ dmypy.json !README.md !CHANGELOG.md !CONTRIBUTING.md +!CLAUDE.md # Sensitive data patterns *.pem diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9f83948 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,132 @@ +# Claude Instructions for TaskRepo Development + +This file provides guidance for AI assistants working on TaskRepo development. + +## Project Overview + +TaskRepo is a TaskWarrior-inspired task management system that stores tasks as markdown files in git repositories. It provides a modern CLI interface with TUI support and GitHub integration. + +## Development Environment + +### Setup +```bash +# Install UV (recommended package manager) +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Install dependencies +uv sync --extra dev + +# Run tests +uv run pytest tests/ -v +``` + +### Code Quality +```bash +# Format code +uv run ruff format . + +# Lint code +uv run ruff check . + +# Type checking +uv run mypy src/taskrepo +``` + +## Release Process + +### Version Bumping + +1. Update version in `pyproject.toml` +2. Update CHANGELOG.md with new release notes +3. Create PR to main +4. Tag release triggers PyPI publication +5. Update Homebrew formula (see below) + +### Homebrew Formula Updates + +TaskRepo is distributed via PyPI and Homebrew. After the PyPI release is live, update the Homebrew formula. + +#### Homebrew Formula Location + +The Homebrew formula is maintained in a separate repository located at `../homebrew-formulas`: +- **Repository**: `../homebrew-formulas/` +- **Formula file**: `Formula/taskrepo.rb` +- **Automation**: Managed via justfile commands + +#### Commands + +After the PyPI release is live and verified at https://pypi.org/project/taskrepo/: + +```bash +cd ../homebrew-formulas + +# Option 1: Full automated release workflow (recommended) +# This will update, test, commit, and push in one command +just release taskrepo + +# Option 2: Manual step-by-step workflow +just update taskrepo # Updates to latest PyPI version +just test taskrepo # Tests the formula installation +just commit taskrepo VERSION # Commits with standardized message +git push # Push to remote + +# Utility commands +just list # List all formulas with current versions +just check-updates # Check for available PyPI updates +just sha256 taskrepo VERSION # Get SHA256 for a specific version +``` + +#### Workflow Notes + +- **Always verify PyPI first**: The formula update pulls package info from PyPI, so the release must be live +- **Automatic metadata**: The `just update` command automatically fetches the version, download URL, and SHA256 checksum from PyPI +- **Full automation**: The `just release` command runs the complete workflow: update → test → commit → push +- **Standardized commits**: Formula updates use consistent commit message format +- **Testing**: The `just test` command uninstalls and reinstalls the formula to verify it works correctly + +## Key Features + +### Task Management +- Tasks stored as markdown files with YAML frontmatter +- Git-based version control and synchronization +- Support for tags, priorities, due dates, and dependencies +- Rich CLI with color-coded output + +### Repository Support +- Multiple task repositories +- GitHub integration for remote storage +- Discovery and initialization commands +- Automatic syncing capabilities + +### TUI Components +- Interactive prompts using questionary +- Rich formatting for better UX +- Progress bars and status indicators + +## Testing Strategy + +- **Unit tests**: Individual component testing +- **Integration tests**: End-to-end workflow testing +- Use pytest with fixtures for common setups +- Aim for >80% test coverage + +## Code Style + +- Follow PEP 8 style guide +- Use type hints for all function signatures +- Google-style docstrings for public functions +- Ruff for linting and formatting + +## Important Notes + +- Tasks are stored in `~/.taskrepo/` by default or in user-configured locations +- Each repository is a git repository with tasks as markdown files +- YAML frontmatter contains task metadata +- GitHub integration requires `gh` CLI tool + +## Security Considerations + +- Sanitize user input for file paths +- Validate repository URLs +- Handle git credentials securely +- Avoid exposing sensitive data in task files diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3eea73..c64a15c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,39 +31,63 @@ uv run pytest tests/ -v ## Updating the Homebrew Formula -When releasing a new version of TaskRepo, update 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). -### 1. Get Package Information from PyPI +### Automated Workflow (Recommended) ```bash -VERSION=0.10.17 # Replace with new version +cd ../homebrew-formulas +just release taskrepo # 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, you can update the formula manually: + +#### 1. Get Package Information from PyPI + +```bash +VERSION=X.Y.Z # Replace with new version curl "https://pypi.org/pypi/taskrepo/$VERSION/json" | \ jq -r '.urls[] | select(.packagetype=="sdist") | "URL: \(.url)\nSHA256: \(.digests.sha256)"' ``` -### 2. Update the Formula +#### 2. Update the Formula + +Navigate to the homebrew-formulas repository and edit the formula: + +```bash +cd ../homebrew-formulas # Use relative path from TaskRepo directory +``` -Edit `homebrew-formulas/Formula/taskrepo.rb`: +Edit `Formula/taskrepo.rb`: - Update the `url` line with the new URL - Update the `sha256` line with the new hash -### 3. Test Locally +#### 3. Test Locally ```bash -cd ~/GitHub/homebrew-formulas brew install --build-from-source ./Formula/taskrepo.rb brew test taskrepo tsk --version # Verify correct version brew uninstall taskrepo ``` -### 4. Audit the Formula +#### 4. Audit the Formula ```bash brew audit --strict --online taskrepo ``` -### 5. Commit and Push +#### 5. Commit and Push ```bash git add Formula/taskrepo.rb @@ -71,13 +95,15 @@ git commit -m "taskrepo: update to version $VERSION" git push ``` -### 6. Verify Installation +#### 6. Verify Installation ```bash brew install henriqueslab/formulas/taskrepo tsk --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` + ## Development Workflow ### Making Changes