Contributing

Plumego is intentionally conservative.

Contributing to Plumego is not primarily about code volume,
feature velocity, or community growth.

It is about protecting a small, explicit, long-lived core.

This section explains:

• What contributions are welcome
• What contributions are discouraged or rejected
• How decisions are evaluated
• What responsibility comes with changing Plumego

If you want to help Plumego grow,
this page matters more than any API reference.

Contribution Philosophy

Plumego follows a simple rule:

Every contribution must reduce long-term risk, not increase short-term convenience.

This applies to:

• Code changes
• Documentation
• Examples
• Tooling
• Design discussions

If a contribution makes Plumego more exciting but less predictable,
it will be rejected.

What Contributions Are Most Valuable

Not all contributions are equal.

The following categories are actively encouraged.

1. Documentation Improvements

Documentation is considered part of the framework.

High-value documentation contributions include:

• Clarifying ambiguous behavior
• Explaining trade-offs more clearly
• Adding failure-mode explanations
• Improving reference precision
• Correcting misleading phrasing

If code and documentation disagree,
documentation defines intent.

2. Bug Fixes (Behavior-Preserving)

Bug fixes are welcome when they:

• Restore documented behavior
• Remove undefined behavior
• Improve correctness without changing semantics
• Reduce edge-case surprises

Bug fixes must not introduce new behavior implicitly.

3. Examples and Reference Implementations

Examples help users learn without expanding the core.

Valuable examples include:

• Production-style service layouts
• Explicit wiring demonstrations
• Testing strategies
• Migration patterns
• Integration patterns

Examples should teach thinking, not shortcuts.

4. Tooling (Outside the Core)

Optional tooling is welcome when it:

• Lives outside the core runtime
• Is opt-in
• Does not affect runtime semantics
• Helps detect misuse early

Examples:

• Linters
• Static analysis helpers
• Project templates
• Documentation generators

Contributions That Are Usually Rejected

The following contributions are typically not accepted.

Understanding why is more important than memorizing the list.

1. Core Feature Expansion

Requests to add:

• DI containers
• ORMs
• Background job systems
• Configuration frameworks
• Auto-routing
• Convention-based behavior

Are almost always rejected.

These violate documented non-goals.

2. Convenience APIs That Hide Control Flow

Any API that:

• Implicitly alters execution
• Introduces magic defaults
• Hides lifecycle decisions
• Automates error handling

Will be rejected, even if popular.

3. Framework-Owned State

Changes that introduce:

• Global registries
• Shared mutable state
• Hidden caches
• Implicit singletons

Are incompatible with Plumego’s guarantees.

4. “Everyone Else Has This” Arguments

Popularity is not a design argument.

If a feature is proposed because:

• Other frameworks have it
• It is fashionable
• It reduces boilerplate

It will be rejected unless it also reduces long-term risk.

How Design Decisions Are Evaluated

All changes are evaluated against a fixed checklist.

Key questions include:

• Does this introduce hidden behavior?
• Does this weaken explicit control flow?
• Does this expand the core unnecessarily?
• Does this reduce replaceability?
• Does this complicate reasoning under failure?
• Can this live outside the core instead?

A single “yes” may be enough to reject a change.

Contribution Does Not Mean Acceptance

Submitting a contribution does not imply:

• It will be merged
• It aligns with Plumego’s goals
• It will be maintained long-term

Rejection is not a judgment of quality —
it is a judgment of fit.

The Responsibility of Contributors

Contributing to Plumego means accepting responsibility for:

• Long-term maintenance cost
• Documentation accuracy
• Migration impact
• User trust

Every merged change becomes a promise.

Plumego is careful about making promises.

Governance and Ownership

Plumego uses a benevolent dictator model:

• Final design authority is centralized
• Decisions prioritize coherence over consensus
• Discussion is welcome
• Direction is deliberate

This avoids fragmentation and design drift.

How to Propose a Change

Before writing code:

1. Read the Roadmap
2. Read Design Principles
3. Read Non-Goals
4. Read relevant Reference pages
5. Clearly articulate the problem being solved
6. Explain why it cannot live outside the core

Most proposals fail at step 6.

Pull Requests

When submitting a PR:

• Keep scope minimal
• Avoid unrelated refactors
• Preserve explicit behavior
• Update documentation if behavior is affected
• Assume reviewers are protecting the framework, not blocking you

Small, precise PRs are preferred.

Issues and Discussions

Issues are welcome when they:

• Report reproducible bugs
• Identify documentation gaps
• Ask clarification questions
• Propose ideas with clear trade-off analysis

Issues are not feature request dumping grounds.

Contributing Without Code

You can meaningfully contribute by:

• Writing about Plumego usage
• Sharing migration experiences
• Providing feedback on clarity
• Identifying confusion points
• Improving examples

Plumego values understanding over churn.

Summary

Contributing to Plumego is not about growth.

It is about preservation.

• Preserve clarity
• Preserve explicitness
• Preserve trust
• Preserve longevity

If that responsibility excites you,
you are welcome here.

Next

From here, useful next pages include:

• Contribution Workflow — practical steps and etiquette
• Decision Records — why past decisions were made
• Code Style and Conventions — consistency rules

Plumego evolves slowly — on purpose.