Skip to content

docs: align Homebrew workflow with automation and add CLAUDE.md #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
paxcalpt merged 1 commit into from
Feb 2, 2026
Merged

docs: align Homebrew workflow with automation and add CLAUDE.md #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ dmypy.json
!README.md
!CHANGELOG.md
!CONTRIBUTING.md
!CLAUDE.md

# Sensitive data patterns
*.pem
Expand Down
132 changes: 132 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The version should be updated in src/taskrepo/__version__.py, not pyproject.toml. The pyproject.toml file uses dynamic = ["version"] and references the version from src/taskrepo/__version__.py via the hatch configuration at line 121.

Suggested change
1. Update version in `pyproject.toml`
1. Update version in `src/taskrepo/__version__.py` (version is read dynamically in `pyproject.toml`)

Copilot uses AI. Check for mistakes.
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
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The project uses prompt_toolkit for interactive prompts, not questionary. This can be verified in pyproject.toml line 29 which lists "prompt_toolkit>=3.0.0" as a dependency.

Suggested change
- Interactive prompts using questionary
- Interactive prompts using prompt_toolkit

Copilot uses AI. Check for mistakes.
- 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
46 changes: 36 additions & 10 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,53 +31,79 @@ 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
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`
Copy link

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sentence is missing a period at the end. It should end with "...and just sha256." to match standard punctuation conventions.

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`.

Copilot uses AI. Check for mistakes.

## Development Workflow

### Making Changes
Expand Down