# PR Best Practices

## Best Practice: Single PR for Related Changes

For all categories of changes that are **closely related**, they should be in one PR because:

### 1. **Atomic Change Principle**
- The main code change, tests, and documentation all serve the same purpose: e.g. [Ref: Issue #619](https://github.com/pyqtgraph/pyqtgraph/issues/619) making `ItemSample` publicly available
- They form a complete, logical unit of work
- Splitting them would create incomplete states in the codebase

### 2. **Review Efficiency**
- Reviewers can see the complete picture in one place
- Easier to understand the context and impact
- Reduces reviewer fatigue from multiple related PRs

### 3. **Git History Cleanliness**
- One commit/PR = one feature/fix
- Easier to track, revert, or reference later
- Cleaner git log

## When to Split PRs

You would create **separate PRs** when:

````markdown
❌ **Don't Split** (like example case):
- Bug fix + tests + docs for the same bug
- Feature + tests + docs for the same feature
- Refactoring + updating related tests

✅ **Do Split**:
- Multiple unrelated issues
- Large feature that can be broken into independent parts
- Different types of changes (e.g., bug fix + new feature)
- Changes that might need different review timelines
````

## Recommended PR Structure

Your single PR should include:

````markdown
## PR Title
Add ItemSample to __all__ list in LegendItem module

## Description
Fixes #619

- Add ItemSample to __all__ list to make it part of public API
- Add test to verify ItemSample can be imported and subclassed  
- Update documentation

## Changes Made
- [x] Modified LegendItem.py to include ItemSample in __all__
- [x] Added test case for ItemSample import/subclassing
- [x] Updated docs
````

## Commit Strategy

You can either:
1. **Single commit** with all changes
2. **Multiple commits** in one PR:
   - Commit 1: "Add ItemSample to __all__ list"
   - Commit 2: "Add tests for ItemSample public API"
   - Commit 3: "Update documentation for ItemSample"

Both approaches are fine, but for a simple change like this, a single commit is perfectly acceptable.