@@ -91,73 +91,51 @@ flowchart TB
9191
9292### Package Graduation Criteria
9393
94- A package must meet ALL of the following criteria to graduate to ` toolhive-core ` :
94+ Packages can graduate via two tracks depending on complexity :
9595
96- #### 1. Stability Requirements
96+ #### Fast Track (Simple Packages)
97+
98+ For small, focused packages with minimal dependencies (e.g., ` env ` , ` errors ` , ` validation ` ):
9799
98100| Criterion | Requirement |
99101| -----------| -------------|
100- | ** Production usage** | Deployed in production for ≥3 months without breaking changes |
101- | ** API stability** | No breaking changes in the last 2 minor releases |
102- | ** Interface design** | Uses Go interfaces for dependency injection and testability |
103- | ** Error handling** | Returns typed errors; no panics except for programming bugs |
102+ | ** Production usage** | Deployed in production for ≥1 month |
103+ | ** No internal dependencies** | Cannot depend on non-graduated internal packages |
104104| ** No global state** | No singletons, global variables for state, or ` init() ` side effects |
105+ | ** Test coverage** | ≥70% line coverage |
106+ | ** Documentation** | Package-level godoc |
107+ | ** Approval** | GitHub issue approved by one maintainer |
108+
109+ #### Standard Track (Complex Packages)
105110
106- #### 2. Quality Requirements
111+ For packages with external dependencies, multiple types, or broader API surface:
107112
108113| Criterion | Requirement |
109114| -----------| -------------|
110- | ** Test coverage** | ≥80% line coverage with meaningful assertions |
111- | ** Mock support** | Interfaces have mock implementations (mockgen or similar) |
115+ | ** Production usage** | Deployed in production for ≥2 months without breaking changes |
116+ | ** API stability** | No breaking changes in the last 2 minor releases |
117+ | ** Interface design** | Uses Go interfaces for dependency injection and testability |
118+ | ** Error handling** | Returns typed errors; no panics except for programming bugs |
119+ | ** No global state** | No singletons, global variables for state, or ` init() ` side effects |
120+ | ** Test coverage** | ≥70% line coverage with meaningful assertions |
112121| ** Documentation** | Package-level godoc with usage examples |
113122| ** Linting** | Passes ` golangci-lint ` with project configuration |
114-
115- #### 3. Dependency Requirements
116-
117- | Criterion | Requirement |
118- | -----------| -------------|
119123| ** Minimal dependencies** | Only essential external dependencies |
120124| ** No circular imports** | Must not create import cycles when extracted |
121125| ** No internal dependencies** | Cannot depend on non-graduated internal packages |
122126| ** Stable external deps** | External dependencies must be v1.0+ or widely adopted |
123-
124- #### 4. Governance Requirements
125-
126- | Criterion | Requirement |
127- | -----------| -------------|
128127| ** Sponsorship** | At least one maintainer sponsors the graduation |
129- | ** RFC approval** | Graduation proposal reviewed and approved |
130- | ** Migration plan** | Clear plan for consumers to adopt the graduated package |
128+ | ** Approval** | RFC or detailed GitHub issue reviewed and approved |
131129
132130### Graduation Process
133131
134- ``` mermaid
135- sequenceDiagram
136- participant C as Contributor
137- participant M as Maintainers
138- participant RFC as RFC Process
139- participant Core as toolhive-core
140-
141- C->>M: Propose package graduation
142- M->>M: Evaluate against criteria
143- alt Criteria not met
144- M->>C: Feedback: criteria gaps
145- C->>C: Address gaps
146- else Criteria met
147- M->>RFC: Create graduation RFC
148- RFC->>M: Review & approval
149- M->>Core: Extract package
150- M->>Core: Release new version
151- M->>C: Update consumer repos
152- end
153- ```
154-
155- 1 . ** Proposal** : Contributor or maintainer identifies a graduation candidate
156- 2 . ** Evaluation** : Maintainers assess the package against all graduation criteria
157- 3 . ** RFC** : Create a lightweight RFC documenting the graduation (can be a GitHub issue for simple cases)
158- 4 . ** Extraction** : Move package to ` toolhive-core ` with necessary adaptations
159- 5 . ** Release** : Tag a new semver release of ` toolhive-core `
160- 6 . ** Migration** : Update consuming projects to import from ` toolhive-core `
132+ 1 . ** Proposal** : Open a GitHub issue identifying the graduation candidate and proposed track (fast/standard)
133+ 2 . ** Track determination** : Maintainers confirm which track applies based on package complexity
134+ 3 . ** Evaluation** : Assess against the relevant track's criteria
135+ 4 . ** Approval** : Fast track requires one maintainer approval; standard track requires RFC or detailed issue review
136+ 5 . ** Extraction** : Move package to ` toolhive-core ` with necessary adaptations
137+ 6 . ** Release** : Tag a new semver release of ` toolhive-core `
138+ 7 . ** Migration** : Update consuming projects to import from ` toolhive-core `
161139
162140### Stability Levels
163141
0 commit comments