Skip to content

Instantly share code, notes, and snippets.

@pizofreude

pizofreude/PR.md

Last active October 5, 2025 15:58
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save pizofreude/6c6767fd696c53cc3fecec3f91eca35e to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save pizofreude/6c6767fd696c53cc3fecec3f91eca35e to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. pizofreude revised this gist Oct 5, 2025. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion PR.md
    View file
    Original file line number Diff line number Diff line change
    @@ -24,7 +24,7 @@ For all categories of changes that are **closely related**, they should be in on
    You would create **separate PRs** when:

    ````markdown
    ❌ **Don't Split** (like your case):
    ❌ **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
  2. pizofreude created this gist Oct 5, 2025.
    69 changes: 69 additions & 0 deletions PR.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,69 @@
    # 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 your 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.