Docs Contribution Philosophy

Contribution Philosophy

Plumego is not optimized for growth.

It is optimized for survival.

Contributing to Plumego means participating in the maintenance
of a framework that is intentionally small, explicit, and long-lived.

This page explains the philosophy behind that choice,
and the mindset required to contribute responsibly.

Plumego Is a Tool for the Long Term

Most frameworks fail not because they are bad,
but because they accumulate decisions they cannot undo.

Plumego exists to avoid that fate.

Its philosophy is built around a single assumption:

The cost of change grows faster than the benefit of features.

Contributors must treat every change
as a potential long-term liability.

Restraint Is the Primary Virtue

In Plumego, restraint is not conservatism.
It is an engineering strategy.

Good contributions often look like:

  • Saying “no” to a feature
  • Removing ambiguity
  • Simplifying an interface
  • Clarifying documentation
  • Reducing surface area

Bad contributions often look like:

  • Adding convenience
  • Increasing abstraction
  • Reducing visible complexity by hiding it
  • Making the framework “friendlier” at the cost of clarity

Restraint preserves optionality.

Every Change Is a Promise

When a change is merged into Plumego, it becomes:

  • A promise to users
  • A contract with future maintainers
  • A dependency in unknown systems

Breaking that promise later is expensive.

Therefore:

Changes must earn their permanence.

Popularity Is Not a Signal

Plumego explicitly rejects popularity as a decision input.

A feature is not justified because:

  • “Everyone else has it”
  • “Users are asking for it”
  • “It’s industry standard”
  • “It reduces boilerplate”

Popularity measures demand, not suitability.

Plumego optimizes for coherence, not adoption.

Explicitness Is an Ethical Choice

Plumego treats explicitness as an ethical stance.

Hidden behavior:

  • Transfers responsibility from users to the framework
  • Obscures failure modes
  • Creates false confidence
  • Makes debugging harder under pressure

Explicit behavior:

  • Makes ownership clear
  • Makes trade-offs visible
  • Makes failure understandable

Contributors must preserve this ethic.

Boring Code Is a Feature

Plumego values code that is:

  • Obvious
  • Predictable
  • Unremarkable
  • Easy to reason about

Cleverness is treated with suspicion.

If a change is impressive,
it is probably not appropriate for the core.

Boring code survives longer than clever code.

Maintenance > Innovation

Innovation is easy.
Maintenance is hard.

Plumego prioritizes:

  • Ease of understanding
  • Ease of debugging
  • Ease of replacement
  • Ease of explaining to new contributors

If a change makes maintenance harder,
it must deliver exceptional long-term value to justify itself.

Most do not.

The Framework Does Not Exist to Save Users

Plumego does not try to:

  • Protect users from mistakes
  • Enforce “best practices” automatically
  • Prevent bad architecture
  • Hide complexity

Instead, it exposes reality honestly.

Contributors should not add features
that “help users” by obscuring responsibility.

You Are Writing for Unknown Engineers

When contributing, assume that:

  • You will not maintain this code forever
  • Users will outnumber contributors
  • Context will be lost
  • Decisions will be questioned years later

Your contribution should be defensible
without relying on personal memory or intent.

Reversibility Matters More Than Power

A key question for any contribution is:

“How hard will this be to remove?”

If the answer is:

  • “Very hard”
  • “Impossible without breaking users”
  • “It would require a major rewrite”

Then the bar for acceptance is extremely high.

Irreversible power is dangerous.

Slow Is a Feature

Plumego evolves slowly on purpose.

Slow evolution allows:

  • Reflection
  • Validation
  • Real-world feedback
  • Avoidance of reactive decisions

Urgency is not considered a virtue.

Disagreement Is Healthy, Fragmentation Is Not

Plumego welcomes disagreement and discussion.

However:

  • Decisions are eventually made
  • Not all opinions are equal
  • Coherence outweighs consensus

Once a decision is made,
contributors are expected to respect it.

Forking is always an option —
fragmentation is not encouraged.

Contributing Is Optional, Responsibility Is Not

No one is obligated to contribute to Plumego.

But if you do contribute,
you accept responsibility for:

  • The clarity of your change
  • The maintenance cost it introduces
  • The trust it affects
  • The users who depend on it

This responsibility does not end at merge time.

Summary

Plumego’s contribution philosophy can be summarized simply:

  • Prefer clarity over convenience
  • Prefer restraint over expansion
  • Prefer honesty over protection
  • Prefer longevity over novelty

Contributing to Plumego is not about leaving your mark.

It is about leaving as little mark as possible,
while improving what truly matters.

  • Decision Process — how philosophy becomes decisions
  • Code Structure — where philosophy is enforced
  • Documentation Guide — how philosophy is communicated
  • Workflow — how philosophy is applied in practice

Plumego survives not because it grows fast,
but because it grows carefully.