# RFC (Overview): Restructuring mellea-contribs for Bleeding-Edge Contributions
#56
Replies: 5 comments 3 replies
-
|
I'm on board with the general plan |
Beta Was this translation helpful? Give feedback.
-
|
I've re-read this a couple times and I'm a big fan of the overall pitch, but I have reservations about the mirroring of mellea's structure. I'm having trouble putting it into words but it feels like it's unnecessary complex compared to each contrib being in their own dirs. Perhaps enforcing the dir structure per contrib rather than combining them would work? |
Beta Was this translation helpful? Give feedback.
-
I'd back off of this framing. The success path for something in The primary motivation for mirroring We shouldn't frame inclusion in |
Beta Was this translation helpful? Give feedback.
-
I think we want this to be more like |
Beta Was this translation helpful? Give feedback.
-
|
Problem statement:
uv pip install mellea[all] mellea-contribs[all]This one-liner gets you all the toys and is the "how to get started" install instruction.
The graduation thing isn't false but is mostly a red herring. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
RFC (Overview): Restructuring
mellea-contribsfor Bleeding-Edge Contributionsgenerative-computing/mellea-contribs(independent ofgenerative-computing/mellea)1. Executive Summary — Why We Need This
Mellea has no sanctioned home for bleeding-edge contributions — novel sampling algorithms, third-party framework bridges (DSPy, LangChain, CrewAI), domain-specific requirements, and incubating research code. The
mellea-contribsrepo was created to fill that gap, but six subpackages in, it's already accumulating the kind of structural drift that becomes unfixable at scale: inconsistent layouts, ad-hoc CI, no archival story for unmaintained code, and import paths that bear no relation to where the code would live if it graduated into core.Two concrete consequences today:
pip installthis."Both gaps compound as contribs grows. There are six subpackages now, not sixty. This is the cheap moment to lock in structure.
This RFC proposes three load-bearing changes:
The structure (1) makes graduation (3) cheap. The eviction contract (2) keeps the repo healthy as new contributions arrive. They reinforce each other; neither works alone.
2. Proposed Structure: Mirror Core
mellea/The headline change: a contribs subpackage's source layout is identical to where its code would live if it were in core
mellea.Examples:
mellea/stdlib/sampling_algos/my_algo.pymellea_contribs/stdlib/sampling_algos/my_algo.pymellea/stdlib/frameworks/dspy.pymellea_contribs/stdlib/frameworks/dspy/mellea/stdlib/requirements/python_imports.pymellea_contribs/stdlib/requirements/python_imports.pymellea/backends/my_experimental_backend.pymellea_contribs/backends/my_experimental_backend.pyThe only path difference between contribs and core is the top-level prefix:
mellea_contribs.vs.mellea..What this gives us
uv add "mellea-contribs[stdlib.frameworks.dspy]"), so users pull only what they need and heavy dependencies don't leak across subpackages.pyproject.tomlshape, same test directory name, same required files (OWNERS,README.md,tests/,examples/). Drift becomes a CI failure, not a reviewer's burden.The full RFC explains how the contribution path works (cookiecutter scaffold, validate-structure CI gate); this overview just commits to the shape.
3. Graduation: From Contribs to Core
The structure (Section 2) directly enables graduation as a near-zero-cost motion. When a contribs subpackage proves itself — stable API, sustained user adoption, owners willing to commit to core's stability bar — it can move into core via:
…plus a one-prefix import bump for users:
That's the entire mechanical change. No file restructuring, no API redesign, no rewrite. The contribs side leaves a re-export shim with a
DeprecationWarningfor one Mellea release cycle, then drops it.Why this matters
Graduation that costs a rewrite never happens. Promising experimental code stagnates in contribs because the migration tax is too high, or worse, gets reimplemented from scratch in core, losing the original contributor's involvement. By making the contribs path identical to the eventual core path, the cost of graduation collapses to a code review and a search-and-replace — and the original author stays in the loop because their code, not a rewritten version, is what lands.
What graduation is and isn't
This RFC commits to:
This RFC explicitly does not commit to:
The point here is that the option is structurally cheap. When and how to exercise it remains an editorial call.
4. Eviction: Clean Exits for Unmaintained Code
The flip side of "make it easy to contribute" is "make it safe to leave." Without a documented eviction path, contribs becomes a junkyard of half-maintained code that scares off both new contributors (who don't want to inherit ambiguity) and users (who can't tell which subpackages are alive).
What we commit to
When a contribs subpackage breaks and its
OWNERSdon't fix it within a documented grace window, we archive it:mellea-contribs[all]and from the meta-package's published extras list.ARCHIVED.mdexplaining why and how to revive — code is never deleted.What this gives us
mellea-contribs[all]. No more guessing from commit timestamps.The full RFC specifies the implementation: a 21-day timeline driven by per-subpackage CI failures, owner-pings via auto-opened issues, and the release-time logic that drops red subpackages from the next published
[all]extra. This overview just commits to the contract.5. How These Three Pieces Fit Together
Read in order:
A contribs subpackage's lifecycle, end-to-end:
flowchart LR A([New contribution]) -->|cookiecutter PR<br/>passes structure gate| B[Active in contribs] B -->|stable + adopted<br/>graduation RFC merged| G([Graduated to core mellea]) B -->|CI red, no fix in 21 days| C[Archived] C -->|revival PR<br/>restores green CI| B G -.->|deprecation shim<br/>one release cycle| B classDef terminal fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#000 classDef archived fill:#f8d7da,stroke:#dc3545,stroke-width:2px,color:#000 classDef active fill:#cce5ff,stroke:#0066cc,stroke-width:2px,color:#000 classDef start fill:#fff3cd,stroke:#856404,stroke-width:2px,color:#000 class A start class B active class C archived class G terminalReading the diagram:
6. What's Out of Scope
feat-mellea-contribs-restructure.md).0.x; breaking changes between minors are fine and expected.7. The Decision This RFC Is Asking For
Three commitments:
If these three land, the implementation work in the full RFC follows as plumbing. If any of them is wrong, the full RFC's plumbing is solving the wrong problem.
Beta Was this translation helpful? Give feedback.
All reactions