Skip to content

Commit 0616c79

Browse files
JAORMXclaude
andcommitted
Add two-track graduation system with relaxed criteria
- Fast Track: For simple packages (env, errors, validation) - 1 month production usage - 70% coverage - GitHub issue approval by one maintainer - Standard Track: For complex packages - 2 months production usage - 70% coverage - RFC or detailed issue review Reduces friction for obvious candidates while maintaining rigor for complex packages. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent c3df847 commit 0616c79

1 file changed

Lines changed: 26 additions & 48 deletions

File tree

rfcs/THV-0032-toolhive-core-shared-library.md

Lines changed: 26 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)