Docs Contribution Workflow

Contribution Workflow

Plumego contributions follow a deliberate, low-noise workflow.

This workflow is designed to:

  • Encourage thoughtful proposals
  • Minimize wasted effort
  • Protect design coherence
  • Make decisions explicit and traceable

Speed is not the primary goal.
Clarity and correctness are.

Overview

A typical contribution flows through the following stages:

Observation → Issue → Discussion → Proposal → Pull Request → Review → Merge (or Reject)

Not every contribution passes through every stage,
but skipping stages increases the chance of rejection.

Stage 1: Observation

Most contributions start with an observation, such as:

  • Confusing documentation
  • Ambiguous behavior
  • Unexpected edge cases
  • Friction in real usage
  • Inconsistency with design principles

Good observations are:

  • Concrete
  • Reproducible
  • Clearly scoped

Vague dissatisfaction is not actionable.

Stage 2: Issue

Issues are used to clarify and validate problems,
not to demand features.

Open an issue when:

  • You believe behavior is unclear or incorrect
  • Documentation does not match reality
  • You want to confirm whether something is intentional
  • You want to discuss a possible change

An effective issue includes:

  • A precise description of the problem
  • What you expected vs what happened
  • Relevant documentation links
  • Minimal reproduction if applicable

Avoid proposing solutions too early.

Stage 3: Discussion

Discussion is where intent is clarified.

During discussion:

  • Maintainers may ask clarifying questions
  • Design principles and non-goals are referenced
  • Alternative interpretations are considered

Outcomes of discussion may include:

  • Confirmation that behavior is correct
  • Agreement that documentation should change
  • Identification of a bug
  • Rejection due to non-goals
  • Green-light for a proposal

Not all discussions lead to changes.

Stage 4: Proposal

For non-trivial changes,
a proposal is expected before code.

A proposal may take the form of:

  • A detailed issue comment
  • A design document
  • A draft PR without implementation
  • A Markdown document

A good proposal explains:

  • The problem being solved
  • Why existing patterns are insufficient
  • How the change aligns with principles
  • What trade-offs are introduced
  • Why the change belongs in Plumego
  • How the change could be undone

Most proposals fail at this stage — by design.

Stage 5: Pull Request

Once a proposal is accepted in principle,
a Pull Request may be opened.

PRs must follow the Pull Request Guide.

Key expectations:

  • Minimal scope
  • Clear intent
  • Explicit trade-offs
  • Documentation updates where required
  • Tests where appropriate

PRs without context from prior discussion
may be closed or redirected.

Stage 6: Review

Reviews focus on:

  • Explicitness
  • Boundary preservation
  • Dependency direction
  • Long-term maintenance cost
  • Alignment with design philosophy

Review feedback may include:

  • Requested changes
  • Scope reduction
  • Documentation clarification
  • Rejection with explanation

Review cycles are expected.
Fast merges are rare.

Stage 7: Merge or Reject

Merge

A PR is merged when:

  • The problem is well-defined
  • The solution aligns with principles
  • The long-term cost is acceptable
  • Documentation and code agree

Merging is a deliberate act, not an automatic reward.

Reject

Rejection may occur when:

  • The problem is not compelling
  • The change violates non-goals
  • The cost outweighs the benefit
  • The change belongs outside the core

Rejection is final unless new information emerges.

Post-Merge Responsibilities

After merge, contributors are expected to:

  • Clarify questions from users
  • Help maintain the change
  • Update documentation if gaps are found
  • Assist with future refactors if needed

Responsibility does not end at merge.

Fast Paths (Limited)

Some contributions may take a shorter path:

  • Typo fixes
  • Minor documentation clarifications
  • Obvious bug fixes with clear intent

Even in these cases,
maintainers may request discussion.

Slow Paths (Expected)

Changes that typically require more time:

  • Public API changes
  • Behavioral changes
  • Architectural refactors
  • New abstractions
  • Anything affecting lifecycle semantics

These changes are intentionally slow.

Communication Expectations

Contributors are expected to:

  • Be precise and respectful
  • Avoid urgency-based arguments
  • Accept rejection gracefully
  • Separate ideas from identity

Plumego values thoughtful collaboration over consensus.

Forking and Experiments

Forks are welcome for:

  • Experimentation
  • Alternative designs
  • Exploration of different trade-offs

Not all good ideas belong in Plumego.

Forking is a healthy outcome.

Summary

Plumego’s workflow exists to:

  • Reduce accidental complexity
  • Make decisions explicit
  • Preserve long-term trust
  • Avoid reactive evolution

Contributing is not a race.

It is a careful process of making and keeping promises.

  • Contribution Philosophy — why restraint matters
  • Decision Process — how choices are evaluated
  • Pull Request Guide — how PRs are prepared
  • Code Style — how contributions should look

Plumego evolves not through momentum,
but through intentional change.