Orthogonal Edits vs Related Changes: How to Structure Clean Pull Requests

Orthogonal edits are independent modifications like typo fixes or dead code removal that do not affect your primary feature, while related changes are necessary adjustments—such as updating tests or imports—directly required by the main modification.

In the forrestchang/andrej-karpathy-skills repository, understanding the distinction between orthogonal edits vs related changes is essential for maintaining clean, reviewable code. The project's guidelines explicitly warn against mixing these two categories, as doing so can obscure the intent of your pull request and introduce unintended side effects.

What Are Orthogonal Edits?

Orthogonal edits are modifications that are completely independent of the current task or feature being worked on. These changes address unrelated concerns such as cleaning up dead code, fixing typographical errors, or refactoring helper utilities that do not affect the functional behavior of the code being changed.

According to the repository's README.md, contributors sometimes unintentionally modify unrelated parts of the codebase: "They still sometimes change/remove comments and code they don't sufficiently understand as side effects, even if orthogonal to the task."

Characteristics of Orthogonal Edits

• Zero functional impact on the feature being added or fixed
• Cosmetic or maintenance-focused, such as reformatting whitespace or removing unused imports
• Low risk, though they can unintentionally introduce side effects if they touch code the contributor doesn't fully understand

Example: Fixing a Typo in an Unrelated Comment

# Before (orthogonal edit)

def compute_loss(pred, target):
    # TODO: refactor this function later (TODO: refacor)

    return (pred - target) ** 2

# After (orthogonal edit)

def compute_loss(pred, target):
    # TODO: refactor this function later (TODO: refactor)

    return (pred - target) ** 2

This change fixes a spelling error in a comment but does not alter the function's behavior or relate to any feature development in progress.

What Are Related Changes?

Related changes (sometimes called "related edits") are adjustments tied to the primary change. They are made because the primary modification exposes a need for a small tweak elsewhere—such as updating a comment to reflect a new API, adjusting a test that now fails because of the main change, or adding a missing import required by the new code.

Characteristics of Related Changes

• Directly influence the behavior or correctness of the primary change
• Required for the feature to work correctly, including updating docstrings or fixing broken tests
• Higher review risk, as they must be verified to ensure they truly align with the primary change

Example: Updating a Docstring After Renaming a Function

# Primary change: rename function

def new_name(x):
    """Calculate the square."""
    return x * x

# Related change required

def new_name(x):
    """Calculate the square (formerly `old_name`)."""
    return x * x

The docstring update is a related change because it directly results from the function renaming and helps maintain code clarity.

Example: Fixing a Failing Test Caused by the Primary Change

# test_loss.py (fails after primary change)

def test_compute_loss():
    pred = torch.tensor([1.0])
    target = torch.tensor([1.0])
    loss = compute_loss(pred, target)
    assert loss == 0.0          # <-- fails because loss now returns a tensor

# Related change: adapt the test to match new behavior

def test_compute_loss():
    pred = torch.tensor([1.0])
    target = torch.tensor([1.0])
    loss = compute_loss(pred, target)
    assert loss.item() == 0.0   # <-- updated to match new return type

This test modification is related because the primary change altered the return type of compute_loss, necessitating the update to maintain test correctness.

Key Differences Between Orthogonal Edits and Related Changes

The distinction between these two categories comes down to intent and impact:

• Purpose: Orthogonal edits serve purely cosmetic, maintenance, or unrelated refactoring goals, while related changes are required adjustments caused by the primary modification.
• Effect on Feature: Orthogonal edits have no functional impact on the feature being developed, whereas related changes directly influence its behavior or correctness.
• Typical Examples: Orthogonal includes reformatting whitespace or fixing typos in unrelated comments; related includes updating docstrings that mention updated functions or fixing failing unit tests.
• Risk Profile: Orthogonal edits carry low risk unless they unintentionally introduce side effects, while related changes carry higher risk and must be reviewed carefully to ensure alignment with the primary change.

Maintaining this separation helps keep pull requests focused, easier to review, and reduces the chance of introducing accidental bugs.

Practical Guidelines from the Repository

The forrestchang/andrej-karpathy-skills repository provides specific guidance on managing these change types across several key files:

• README.md: Contains the explicit warning about contributors modifying code orthogonal to their task.
• skills/karphy-guidelines/SKILL.md: Provides broader coding guidelines that influence how contributors should categorize their changes.
• EXAMPLES.md: Shows concrete usage patterns where the distinction between task-specific edits and unrelated clean-ups is illustrated.
• CLAUDE.md: Offers internal development policies that reinforce the principle of keeping edits focused and separate.

When you spot an orthogonal edit in a pull request, consider moving it to a separate commit or separate PR unless it is truly required for the primary change.

Summary

• Orthogonal edits are independent cleanup tasks (typos, dead code, formatting) with no functional impact on the primary feature.
• Related changes are necessary adjustments (test updates, docstring changes, import additions) directly caused by the primary modification.
• The README.md in forrestchang/andrej-karpathy-skills explicitly warns against accidentally modifying orthogonal code.
• Keeping these categories separate makes pull requests focused, easier to review, and less prone to bugs.
• Key reference files include skills/karpathy-guidelines/SKILL.md and CLAUDE.md for development policies.

Frequently Asked Questions

Should I combine orthogonal edits with feature changes in a single commit?

No. When you mix orthogonal edits with feature changes, you obscure the intent of your modification and make code reviews more difficult. Move orthogonal edits to a separate commit or pull request so reviewers can focus on the logic of your primary change without distraction.

How do I identify if a change is related or orthogonal?

Ask whether the change is required for your primary modification to function correctly. If you could skip the change and your feature would still work (e.g., fixing a typo in a distant comment), it is orthogonal. If the code breaks without the change (e.g., a missing import or failing test), it is related.

What files govern these guidelines in the repository?

The primary guidance appears in README.md, with additional context in skills/karpathy-guidelines/SKILL.md and CLAUDE.md. These files establish the contribution etiquette and internal development policies regarding orthogonal edits vs related changes.

Can orthogonal edits introduce bugs?

Yes, though the risk is generally low. The README.md specifically warns that contributors sometimes "change/remove comments and code they don't sufficiently understand as side effects." Even cosmetic changes can accidentally alter behavior if you modify code you don't fully understand, so review orthogonal edits carefully before committing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}