Documentation improvements for Claude Code and contributors (#215)

talmo · claude · web-flow · commit e029a8105ce0 · 2025-08-19T15:47:55.000-07:00
* Update CLAUDE.md with Claude Commands section - Document .claude/commands directory structure - Update linting commands to match lint.md - Add quick coverage command from coverage.md - Add PR description generation guidance - Reference command files for easier maintenance 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * Enhance CONTRIBUTING.md with practical developer guidance - Add Quick Start section for rapid onboarding with uv - Expand testing section with local test running examples - Include coverage checking commands and line-by-line annotation - Add code quality checks to PR workflow steps - Include comprehensive PR description guidelines - Add troubleshooting section for common issues - Document OpenCV import error workaround - Add commands for checking PR changes 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * Update CONTRIBUTING.md packaging and publishing documentation - Remove live coverage section (using pytest-watch and VS Code extension) - Fix outdated setup.cfg reference - project uses pyproject.toml - Update PEP references to pyproject.toml standards (PEP 517/518) - Add comprehensive uv build and publish documentation - Include links to official uv package guide - Add TestPyPI publishing instructions - Expand build section to cover both manual and automated releases 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * Simplify PyPI publishing docs to reflect Trusted Publisher setup - Remove PyPI token authentication instructions - Remove TestPyPI references (not used) - Add Trusted Publisher documentation link - Clarify that automated releases use GitHub Actions with Trusted Publisher - Keep minimal manual publishing command for rare cases 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/.claude/commands/coverage.md b/.claude/commands/coverage.md
@@ -0,0 +1,14 @@
+Run tests with coverage.
+
+Command to run:
+```
+uv run pytest -q --maxfail=1 --cov --cov-branch && rm .coverage.* && uv run coverage annotate
+```
+
+The result will be the terminal output and the line-by-line coverage will be in files sitting next to each module with the file naming `{module_name.py},cover`. 
+
+If you are working on a PR, figure out which files were changed and look for coverage specifically in those. If you don't know which files to look for coverage in, use this:
+
+```
+git diff --name-only $(git merge-base origin/main HEAD) | jq -R . | jq -s .
+```
diff --git a/.claude/commands/lint.md b/.claude/commands/lint.md
@@ -0,0 +1,9 @@
+Run linting with `ruff`.
+
+Command:
+
+```
+uv run ruff format sleap_io tests && uv run ruff check --fix sleap_io tests
+```
+
+Then manually fix any remaining errors which cannot be automatically fixed by ruff.
diff --git a/.claude/commands/pr-description.md b/.claude/commands/pr-description.md
@@ -0,0 +1,7 @@
+Update PR description.
+
+Use the `gh` CLI to fetch the current PR description, then update it with a comprehensive description of the changes made in this PR.
+
+If there is an associated issue (linked in the PR metadata or mentioned in the PR description), then use the `gh` CLI to fetch that too to contextualize the work done in the PR.
+
+Include a summary, example usage (for enhancements), API changes, and other notes for future consideration (including reasoning behind design decisions).
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -42,13 +42,12 @@ pip install -e .[dev,all]
 
 ### Linting
 ```bash
-# Linting and format check (MUST pass before committing)
-uv run ruff check sleap_io tests
-uv run ruff format --check sleap_io tests
+# Auto-format and fix linting issues (from .claude/commands/lint.md)
+uv run ruff format sleap_io tests && uv run ruff check --fix sleap_io tests
 
-# Auto-fix linting issues
-uv run ruff check --fix sleap_io tests
-uv run ruff format sleap_io tests
+# Check formatting without making changes
+uv run ruff format --check sleap_io tests
+uv run ruff check sleap_io tests
 ```
 
 ### Testing
@@ -59,8 +58,11 @@ uv run pytest --cov=sleap_io --cov-report=xml tests/
 # Run specific test module
 uv run pytest tests/io/test_slp.py -v
 
-# Check line-by-line coverage for a module
-uv run pytest tests/model/test_labels.py -v --cov=sleap_io --cov-report=json && uv run coverage annotate --include="*/sleap_io/model/labels.py"
+# Quick coverage check with line-by-line annotations (from .claude/commands/coverage.md)
+uv run pytest -q --maxfail=1 --cov --cov-branch && rm .coverage.* && uv run coverage annotate
+
+# Check which files changed in PR for targeted coverage review
+git diff --name-only $(git merge-base origin/main HEAD) | jq -R . | jq -s .
 
 # Watch mode for development
 uv run ptw
@@ -119,6 +121,21 @@ uv add --dev <package>
 uv sync --upgrade
 ```
 
+## Claude Commands
+
+The `.claude/commands` directory contains useful command shortcuts for Claude Code:
+
+- **lint.md**: Auto-format and fix linting issues with ruff
+- **coverage.md**: Run tests with coverage and generate line-by-line annotations  
+- **pr-description.md**: Generate comprehensive PR descriptions using gh CLI
+
+### PR Descriptions
+
+When updating PR descriptions (from .claude/commands/pr-description.md):
+1. Fetch current PR metadata and linked issues using `gh` CLI
+2. Include: Summary, Key Changes, Example Usage, API Changes, Testing, and Design Decisions
+3. Document reasoning behind implementation choices for future reference
+
 ## Common Development Tasks
 
 ### Adding a New I/O Format
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,6 +2,28 @@
 
 This repository follows a set of standard development practices for modern Python packages.
 
+## Quick Start
+
+For developers who want to get started quickly with [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+# Clone and setup
+git clone https://github.com/talmolab/sleap-io && cd sleap-io
+uv sync --all-extras
+
+# Make changes on a new branch
+git checkout -b yourname/feature-name
+
+# Before committing - format and lint
+uv run ruff format sleap_io tests && uv run ruff check --fix sleap_io tests
+
+# Run tests
+uv run pytest tests/
+
+# Check coverage
+uv run pytest -q --maxfail=1 --cov --cov-branch && rm .coverage.* && uv run coverage annotate
+```
+
 ## Development workflow
 
 ### Setting up
@@ -47,8 +69,12 @@ We also recommend setting up `ruff` to run automatically in your IDE.
 
 If using `uv`, ruff is already included in the dev dependencies and can be run with:
 ```
-uv run ruff check
-uv run ruff format
+# Auto-format and fix linting issues
+uv run ruff format sleap_io tests && uv run ruff check --fix sleap_io tests
+
+# Check without making changes
+uv run ruff format --check sleap_io tests
+uv run ruff check sleap_io tests
 ```
 
 Alternatively, you can install it globally with [`pipx`](https://pypa.github.io/pipx/):
@@ -66,10 +92,27 @@ Once you're set up, follow these steps to make a change:
 1. If you don't have push access to the repository, start by [making a fork](https://github.com/talmolab/sleap-io/fork) of the repository.
 2. Switch to the [`main`](https://github.com/talmolab/sleap-io/tree/main) branch and `git pull` to fetch the latest changes.
 3. Create a new branch named `<username>/<feature_name>` with a descriptive title for the change. For example: `talmo/nwb_support` or `talmo/update_dependencies`.
-4. Push as many commits as you want. Descriptive commit messages and titles are optional but recommended.
-5. Open a [Pull Request](https://github.com/talmolab/sleap-io/compare) of your new branch against `main` with a description of your changes. Feel free to create a "Draft" pull request to work on it incrementally.
-6. Once the [tests](#tests-and-standards) pass, request a review from a core developer and make any changes requested.
-7. Once approved, perform a [squash merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits) against `main` to incorporate your changes.
+4. Make your changes and ensure code quality:
+   ```bash
+   # Format and lint your code before committing
+   uv run ruff format sleap_io tests && uv run ruff check --fix sleap_io tests
+   
+   # Run tests to ensure nothing broke
+   uv run pytest tests/
+   
+   # Check test coverage for modified files
+   uv run pytest --cov=sleap_io --cov-report=term
+   ```
+5. Push as many commits as you want. Descriptive commit messages and titles are optional but recommended.
+6. Open a [Pull Request](https://github.com/talmolab/sleap-io/compare) of your new branch against `main` with a description of your changes. Feel free to create a "Draft" pull request to work on it incrementally.
+7. Write a comprehensive PR description including:
+   - Summary of changes
+   - Example usage (for new features)
+   - API changes (if any)
+   - Testing approach
+   - Design decisions and rationale
+8. Once the [tests](#tests-and-standards) pass, request a review from a core developer and make any changes requested.
+9. Once approved, perform a [squash merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits) against `main` to incorporate your changes.
 
 
 ## Tests and standards
@@ -81,7 +124,7 @@ See the [`.github/workflows`](.github/workflows) folder for how our checks are i
 This package uses [`setuptools`](https://setuptools.pypa.io/en/latest/) as a [packaging and distribution system](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/).
 
 Our package configuration is defined in [`pyproject.toml`](pyproject.toml) which contains:
-- Build system configuration
+- Build system configuration (using setuptools)
 - Package metadata and dependencies
 - Optional dependencies (extras)
 
@@ -100,8 +143,8 @@ Best practices for adding dependencies include:
 - Don't pin to a single specific versions of dependencies unless absolutely necessary, and consider using [platform-specific specifiers](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#platform-specific-dependencies).
 
 For more reference see:
-- [Configuring setuptools using `setup.cfg` files](https://setuptools.pypa.io/en/latest/userguide/declarative_config.html)
-- [Setuptools Keywords](https://setuptools.pypa.io/en/latest/references/keywords.html)
+- [PEP 517 - pyproject.toml-based builds](https://peps.python.org/pep-0517/)
+- [PEP 518 - Specifying build dependencies](https://peps.python.org/pep-0518/)
 - [PEP 508 - Dependency specification for Python Software Packages](https://peps.python.org/pep-0508/)
 
 **Note:** We recommend using [`uv`](https://docs.astral.sh/uv/) for fast, reliable Python environment management. For backwards compatibility, a minimal conda environment is defined in [`environment.yml`](environment.yml) that simply installs the package via pip.
@@ -118,25 +161,34 @@ All tests must pass before a PR can be merged.
 
 Tests will be run on every commit across multiple operating systems and Python versions (see [`.github/workflows/ci.yml`](.github/workflows/ci.yml)).
 
+#### Running tests locally
 
-### Coverage
-We check for coverage by parsing the outputs from `pytest` and uploading to [Codecov](https://app.codecov.io/gh/talmolab/sleap-io).
+```bash
+# Run full test suite
+uv run pytest tests/
 
-All changes should aim to increase or maintain test coverage.
+# Run a specific test module
+uv run pytest tests/io/test_slp.py -v
 
-### Live coverage
+# Run a specific test function
+uv run pytest tests/io/test_slp.py::test_load_slp -v
 
-*The following steps are based on [this guide](https://jasonstitt.com/perfect-python-live-test-coverage).*
+# Run with coverage report
+uv run pytest --cov=sleap_io --cov-report=term tests/
 
-1. If you already have an environment installed, ensure you have the latest dev tools (namely `pytest-watch`):
-   - With `uv`: `uv sync --all-extras`
-   - With pip: `pip install -e ."[dev]"`
-2. Install the [Coverage Gutters extension](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters) in VS Code.
-3. Open a terminal and run the test watcher:
-   - With `uv`: `uv run ptw`
-   - With conda: `conda activate sleap-io && ptw`
-   This will generate a new `lcov.info` file when it's done.
-4. Enable the coverage gutters by using **Ctrl/Cmd**+**Shift**+**P**, then **Coverage Gutters: Display Coverage**.
+# Quick coverage check with line-by-line annotations
+uv run pytest -q --maxfail=1 --cov --cov-branch && rm .coverage.* && uv run coverage annotate
+# This creates .py,cover files next to each module showing line-by-line coverage
+
+# Check which files changed in your PR (useful for targeted testing)
+git diff --name-only $(git merge-base origin/main HEAD)
+```
+
+
+### Coverage
+We check for coverage by parsing the outputs from `pytest` and uploading to [Codecov](https://app.codecov.io/gh/talmolab/sleap-io).
+
+All changes should aim to increase or maintain test coverage.
 
 
 ### Code style
@@ -201,21 +253,40 @@ Valid examples:
 0.1.10a2
 ```
 
-### Build
+### Build and Publishing
 The PyPI-compatible package settings are in [`pyproject.toml`](pyproject.toml).
 
 The version number is set in [`sleap_io/version.py`](sleap_io/version.py) in the `__version__` variable. This is read automatically by setuptools during installation and build.
 
-To manually build (e.g., locally):
-```
+#### Building with uv
+
+To build the package locally:
+```bash
+# Build source distribution and wheel
 uv build
+
+# Build artifacts will be placed in dist/
+ls dist/
 ```
-Or with Python's build module:
-```
-python -m build --wheel
+
+For more details, see the [uv guide on building packages](https://docs.astral.sh/uv/guides/package/).
+
+#### Publishing to PyPI
+
+Publishing to PyPI is handled automatically via GitHub Actions using [Trusted Publisher](https://docs.pypi.org/trusted-publishers/). This means no tokens or passwords are needed for releases from GitHub.
+
+For manual/local publishing with `uv` (rarely needed):
+```bash
+# Build and publish
+uv build
+uv publish
 ```
 
-To trigger an automated build (via the [`.github/workflows/build.yml`](.github/workflows/build.yml) action), [publish a Release](https://github.com/talmolab/sleap-io/releases/new).
+See the [uv publishing documentation](https://docs.astral.sh/uv/guides/package/#publishing-packages) for more details.
+
+#### Automated releases
+
+To trigger an automated build and release (via the [`.github/workflows/build.yml`](.github/workflows/build.yml) action), [publish a Release](https://github.com/talmolab/sleap-io/releases/new). The GitHub Action will automatically authenticate with PyPI using Trusted Publisher and upload the built packages.
 
 
 ## Documentation website
@@ -227,3 +298,30 @@ To trigger an automated build (via the [`.github/workflows/build.yml`](.github/w
 2. Build and tag a new version of the docs: `uv run mike deploy --update-aliases 0.1.4 latest`
 3. Preview live changes locally with: `uv run mike serve`
 4. Manually push a specific version with: `uv run mike deploy --push --update-aliases --allow-empty 0.1.4 latest`
+
+## Troubleshooting
+
+### Common Issues
+
+#### OpenCV import errors during testing
+If you encounter cv2/OpenCV import errors when running individual tests:
+- Try running the entire test module instead: `uv run pytest tests/io/test_video.py`
+- Or run the full test suite: `uv run pytest tests/`
+- This is a known OpenCV issue with importing submodules
+
+#### Video backend dependencies
+sleap-io has optional video backend dependencies:
+- Install all backends: `uv sync --all-extras` or `pip install -e .[all]`
+- Install OpenCV only: `pip install -e .[opencv]`
+- Install PyAV only: `pip install -e .[av]`
+
+#### Environment issues
+If you're having environment problems:
+- With `uv`: `uv sync --all-extras --refresh`
+- With conda: `conda env remove -n sleap-io && conda env create -f environment.yml`
+
+#### Finding what changed in your PR
+To see which files you've modified (useful for targeted testing):
+```bash
+git diff --name-only $(git merge-base origin/main HEAD)
+```
