Skip to content

Commit a311e91

Browse files
committed
docs: move 'extract SDK crate' task to additional-improvements as deferred
Task 11 (Extract into a separate crate) moved from phase-2-improvements.md to additional-improvements.md under a new 'Future Phases (Deferred)' section. Rationale: extracting a crate before the SDK has proven real-world adoption would be premature. The right trigger is stable API + community usage. Tasks 12-14 in phase-2-improvements.md renumbered to 11-13 accordingly.
1 parent 540a78a commit a311e91

2 files changed

Lines changed: 37 additions & 24 deletions

File tree

docs/experiments/sdk/additional-improvements.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,37 @@ file, updating a progress bar, or collecting step timings. The current
8686
realistic example would help users building UIs or dashboards on top of
8787
the SDK.
8888

89+
## Future Phases (Deferred)
90+
91+
These improvements are deliberately deferred until the SDK has proven
92+
real-world adoption. Implementing them before the API is stable and
93+
used by the community would be premature optimization.
94+
95+
### Extract into a Separate Crate
96+
97+
A separate `torrust-tracker-deployer-sdk` crate would enable independent
98+
versioning, a smaller dependency footprint for SDK-only consumers, and
99+
cleaner public API boundaries. However, the right time to do this is
100+
**after** the SDK has been adopted and the API has stabilized through
101+
real usagenot before.
102+
103+
**Prerequisite signals**:
104+
105+
- The SDK API has been stable across multiple releases without breaking changes
106+
- At least one external consumer (community tool, script, or integration) is
107+
using the SDK in production
108+
- The PR/RFC for public publishing has community buy-in
109+
110+
**Work** (when the time comes):
111+
112+
- Create `packages/sdk/` as a workspace member
113+
- Move SDK types from `src/presentation/sdk/` to the new crate
114+
- Re-export domain types via the SDK crate's public API
115+
- Keep the deployer lib crate as a dependency of the SDK crate
116+
- Add `#[non_exhaustive]` to all public enums and structs
117+
- Set up independent semver versioning
118+
- Publish to crates.io (or keep private, depending on project policy)
119+
89120
## Lower Priority / Future
90121

91122
### SDK Changelog / Migration Guide

docs/experiments/sdk/phase-2-improvements.md

Lines changed: 6 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -212,24 +212,7 @@ need cleanup guarantees. A RAII guard prevents leaked environments.
212212
- Handle drop errors gracefully (log, don't panic)
213213
- Add an example demonstrating the guard pattern
214214

215-
### Task 11: Extract into a separate crate
216-
217-
**Complexity**: High
218-
**Why**: Once the API stabilizes, a separate `torrust-tracker-deployer-sdk`
219-
crate enables independent versioning, smaller dependency footprint for
220-
SDK-only consumers, and cleaner public API boundaries.
221-
222-
**Work**:
223-
224-
- Create `packages/sdk/` as a workspace member
225-
- Move SDK types from `src/presentation/sdk/` to the new crate
226-
- Re-export domain types via the SDK crate's public API
227-
- Keep the deployer lib crate as a dependency of the SDK crate
228-
- Add `#[non_exhaustive]` to public enums and structs
229-
- Set up independent semver versioning
230-
- Publish to crates.io (or keep private, depending on project policy)
231-
232-
### Task 12: Error handling example
215+
### Task 11: Error handling example
233216

234217
**Complexity**: Simple
235218
**Why**: Neither current example demonstrates error recovery. They both
@@ -245,7 +228,7 @@ implement retry logic — the most common question for programmatic consumers.
245228
- Show retry logic for transient failures (e.g., provision timeout)
246229
- Register in `Cargo.toml`
247230

248-
### Task 13: Create-from-JSON-file example
231+
### Task 12: Create-from-JSON-file example
249232

250233
**Complexity**: Simple
251234
**Why**: `create_environment_from_file()` is the second entry point into
@@ -259,7 +242,7 @@ from the CLI will likely have JSON config files already.
259242
- Show validate → create → show → purge flow
260243
- Register in `Cargo.toml`
261244

262-
### Task 14: Validate config example
245+
### Task 13: Validate config example
263246

264247
**Complexity**: Trivial
265248
**Why**: The `validate()` method is useful for CI pipelines and pre-flight
@@ -287,7 +270,6 @@ checks but has no dedicated example. Demonstrates a use case distinct from
287270
| 8 | Progress listener in builder | Medium | Observability | |
288271
| 9 | Async operations (provision, etc) | High | Full workflow | Done |
289272
| 10 | Scoped environment guard | Medium | Cleanup safety | |
290-
| 11 | Extract into separate crate | High | API stability | |
291-
| 12 | Error handling example | Simple | Documentation | |
292-
| 13 | Create-from-JSON-file example | Simple | Documentation | |
293-
| 14 | Validate config example | Trivial | Documentation | |
273+
| 11 | Error handling example | Simple | Documentation | |
274+
| 12 | Create-from-JSON-file example | Simple | Documentation | |
275+
| 13 | Validate config example | Trivial | Documentation | |

0 commit comments

Comments
 (0)