diff --git a/docs/roadmap/forge-boundary.md b/docs/roadmap/forge-boundary.md index f05bfeb..1ba3aea 100644 --- a/docs/roadmap/forge-boundary.md +++ b/docs/roadmap/forge-boundary.md @@ -48,6 +48,19 @@ dependency direction. ## Targeted end state +### Neutral public destination and explicit forge selection + +Replace `GiteaDestination` with a facade-owned neutral destination type, such as +`DeliveryDestination`, and require explicit forge selection in the public API +and delivery configuration. Gitea is the sole supported selection initially. +An omitted, blank, or unsupported selection produces a validation error; Gitea +is selected explicitly rather than inferred from a default or destination URL. + +The destination represents the addressing and credentials needed for current +delivery through neutral public names. Concrete backend construction uses the +selected forge. Additional backends may extend that model when their addressing +and protocol requirements are implemented. + ### Shared delivery responsibilities Shared internal code owns: @@ -101,8 +114,8 @@ plugin protocol. - Represent the observed release data needed by current comparisons without making Gitea wire structures part of the generic model. Keep numeric-ID and repository-path-segment validation with the Gitea implementation. -- Put concrete backend construction in composition code. Apply the public - destination choice recorded under Open Decisions. +- Put concrete backend construction in composition code, using the explicitly + selected forge from the neutral public destination. ### 2. Extract shared policy and artifact mechanics @@ -124,6 +137,9 @@ plugin protocol. ### 3. Adapt Gitea and reconnect the facade and CLI +- Replace `GiteaDestination` with the neutral facade-owned destination and add + required forge selection to the public API and delivery profile. Validate + omitted, blank, and unsupported selections without assuming Gitea. - Implement the internal contract with the Gitea client. Keep Gitea JSON decoding, HTTP status interpretation, URL escaping, credential forwarding, redirect behavior, and upload transport in the adapter. @@ -146,11 +162,15 @@ plugin protocol. boundary; reuse existing behavioral cases and consolidate redundant coverage. - Retain representative public-facade and CLI workflows proving that Gitea page-only delivery, binary delivery, tagged retries, and failure reporting - continue to work through the assembled boundary. + continue to work through the assembled boundary with explicit Gitea selection. + Cover missing, blank, and unsupported selections in destination validation. - Update the internal inventory and delivery documentation when implementation lands. Keep Gitea protocol details in the integration guide and shared orchestration details in internal documentation. Update public GoDoc, - configuration, examples, and migration guidance if the destination API changes. + configuration, examples, and ReleaseKit's own profile for the neutral + destination and explicit Gitea selection. Supply migration guidance in the + next minor release for the public type replacement and profile changes, + consistent with the project's direct-cutover approach. - Record the accepted architectural boundary in an ADR when its design is settled, following the [documentation policy](../policy/documentation.md#architecture-decision-records). @@ -171,32 +191,11 @@ client. Keep the test collaborator proportionate to the cases it protects. Completion means the shared workflow and asset policy have independent internal ownership, the Gitea adapter implements the boundary, the existing Gitea contracts pass through that boundary, and documentation describes the resulting -structure. The public API/configuration choice is reflected consistently in -declarations, profiles, examples, and applicable migration guidance. +structure. The neutral public destination and required forge selection are +reflected consistently in declarations, profiles, examples, and migration +guidance. This is an architectural refactor of the implemented Gitea delivery path. Support claims and compatibility testing for additional forges belong to the work that implements those backends. Release preparation and publication continue under the [existing procedure](../release.md). - -## Open Decisions - -### Public destination shape during this refactor - -**Recommendation:** Retain `GiteaDestination` and the existing profile shape -for this pass, with facade/private composition adapting them into the internal -backend. The public type accurately describes the implemented destination, and -the internal seam can be introduced without a consumer migration. A second -backend will provide concrete evidence for repository addressing, API base -URLs, and any provider selection fields. The tradeoff is that the public API -continues to name Gitea until that follow-up API design is implemented. - -**Alternative:** Introduce a facade-owned neutral destination type, such as -`DeliveryDestination`, and an explicit forge selection now, initially dispatching -to Gitea. This makes the consumer-facing shape match the intended multi-forge -direction and allows its migration to happen alongside the internal refactor. -It also adds public/configuration choices before a second backend establishes -their requirements; GitLab project addressing and GitHub API/upload endpoints -may still require later evolution. If selected, define the initial Gitea -selection behavior explicitly and supply migration guidance in the next minor -release, consistent with the project's direct-cutover approach.