Docs Pull Request Guide

Pull Request Guide

Pull requests are the primary way Plumego changes.

They are also the primary mechanism
by which long-term risk enters the codebase.

This guide explains how to prepare a PR
that is likely to be reviewed constructively,
understood clearly,
and evaluated fairly.

Before You Open a Pull Request

Most unsuccessful PRs fail before any code is written.

Before opening a PR, you should be able to answer:

  • What concrete problem does this solve?
  • Where is the problem documented or observable?
  • Why does this belong in Plumego?
  • Why can this not live outside the core?
  • What long-term cost does this introduce?

If any of these answers are unclear,
do not open a PR yet.

Start With an Issue (Usually)

For anything beyond trivial changes,
start with an issue or discussion.

Issues are appropriate for:

  • Behavior clarification
  • Design questions
  • Proposal discussion
  • Ambiguity in documentation
  • Architectural concerns

PRs without prior discussion
are often closed or asked to reframe.

What Makes a Good Pull Request

A good PR is:

  • Small in scope
  • Focused on one concern
  • Easy to reason about
  • Explicit in intent
  • Conservative in impact

If a PR feels “ambitious”,
it is probably too large.

Scope Control (Critical)

Each PR should:

  • Solve one problem
  • Change one conceptual area
  • Avoid unrelated refactors
  • Avoid formatting-only churn

Large PRs are difficult to review
and often hide unintended consequences.

Prefer multiple small PRs over one large one.

What a PR Should Contain

A well-formed PR includes:

1. Clear Description

Explain:

  • The problem being solved
  • Why it matters
  • How the change works
  • What is intentionally not changed

Avoid marketing language.
Be precise and concrete.

2. Explicit Trade-Offs

If the change introduces:

  • More code
  • Less convenience
  • New constraints
  • New maintenance cost

Say so explicitly.

Plumego values honesty over persuasion.

3. Documentation Updates (When Applicable)

If behavior changes or is clarified:

  • Update Reference docs
  • Update Concepts or Architecture if needed
  • Update FAQ if misunderstandings are addressed

PRs that change behavior without documentation
are incomplete.

4. Tests (When Applicable)

Tests should:

  • Demonstrate the intended behavior
  • Protect against regressions
  • Avoid relying on internal details

Tests are not required for every change,
but absence of tests must be justified.

What a PR Should Not Contain

PRs should not include:

  • New features “while we’re here”
  • Broad refactors for style
  • Speculative abstractions
  • Convenience APIs without strong justification
  • Changes that violate non-goals

Bundling unrelated changes
reduces the chance of acceptance.

Commit Guidelines

While Plumego does not enforce a strict commit style,
good commits are:

  • Logically grouped
  • Self-contained
  • Meaningfully named

Avoid:

  • “fix stuff”
  • “cleanup”
  • “WIP” in final commits

Reviewers read commits to understand intent.

Review Expectations

Reviews focus on:

  • Explicitness
  • Boundary preservation
  • Dependency direction
  • Long-term clarity
  • Alignment with design principles

Reviews may feel strict.
This is intentional.

Reviewers are protecting:

  • Users
  • Future maintainers
  • The framework’s guarantees

Common Review Outcomes

1. Accepted As-Is

Rare, but possible for:

  • Documentation improvements
  • Clear bug fixes
  • Very small changes

2. Requested Changes

Most PRs fall here.

This usually means:

  • Scope adjustment
  • Clearer documentation
  • Reduced abstraction
  • Explicit trade-off discussion

This is normal, not a rejection.

3. Reframed or Deferred

Sometimes the idea is valid,
but the timing or scope is not.

In this case:

  • The PR may be closed
  • The idea may be recorded elsewhere
  • Future work may be suggested

4. Rejected

Rejection usually happens because:

  • The change violates principles
  • The change expands the core unnecessarily
  • The long-term cost is too high
  • The problem is better solved elsewhere

Rejection is about fit, not competence.

Responding to Review Feedback

When responding to reviews:

  • Address comments explicitly
  • Ask clarifying questions if needed
  • Avoid defensive language
  • Be willing to simplify or remove code

Plumego values collaboration,
but not endless negotiation.

Updating or Closing a PR

It is acceptable to:

  • Reduce scope
  • Split a PR
  • Close a PR voluntarily
  • Turn a PR into documentation only

Not every idea needs to become code.

Responsibility After Merge

Merging a PR does not end responsibility.

Contributors are expected to:

  • Answer follow-up questions
  • Help with clarification
  • Assist with future refactors if needed
  • Own the intent of the change

Every merged PR becomes part of Plumego’s history.

A Mental Model to Keep in Mind

When opening a PR, imagine this question:

“If this code still exists in five years,
will future engineers thank me for it?”

If the answer is uncertain,
reconsider the change.

Summary

Pull requests in Plumego are not transactions.

They are commitments.

  • Keep them small
  • Keep them explicit
  • Keep them honest
  • Keep them defensible over time

Plumego grows through careful changes,
not momentum.

  • Contribution Philosophy — why restraint matters
  • Decision Process — how PRs are evaluated
  • Code Structure — where changes are allowed
  • Documentation Guide — how intent is recorded

A good PR makes Plumego smaller in risk,
even if it makes the codebase slightly larger.