docs: record SDK migration design
This commit is contained in:
@@ -0,0 +1,138 @@
|
||||
# Yoresee Doc SDK Migration Design
|
||||
|
||||
## Goal
|
||||
|
||||
Publish the protobuf-generated dependencies as two independent repositories under
|
||||
the `YoreseeDoc` Gitea organization and migrate the four services to consume
|
||||
those repositories:
|
||||
|
||||
- `yoresee_doc_sdk_go` for Go protobuf and gRPC stubs.
|
||||
- `yoresee_doc_sdk_node` for browser ESM/Connect RPC stubs and Node.js CommonJS
|
||||
gRPC stubs.
|
||||
|
||||
The existing protobuf repository remains the single source of the `.proto`
|
||||
contract.
|
||||
|
||||
## Scope
|
||||
|
||||
This is a dependency migration, not a code-generation or CI/CD redesign.
|
||||
|
||||
Included:
|
||||
|
||||
- Generate and commit Go, ESM, and CommonJS artifacts in the two SDK repos.
|
||||
- Use the Gitea repositories as versioned service dependencies.
|
||||
- Change service imports to the SDK package paths.
|
||||
- Change the protobuf `go_package` to the canonical Go SDK module path.
|
||||
- Add package documentation describing the generated outputs and source proto.
|
||||
|
||||
Explicitly unchanged:
|
||||
|
||||
- `deploy/script/gen_proto.sh`.
|
||||
- Existing Dockerfiles and Docker Compose files.
|
||||
- Existing local generated-code directories and their fallback generation.
|
||||
- CI/CD workflow and registry setup.
|
||||
|
||||
The existing local generation may continue to produce unused compatibility
|
||||
artifacts during builds. It is intentionally left in place for this migration.
|
||||
|
||||
## Public Package Contracts
|
||||
|
||||
### Go
|
||||
|
||||
The Go SDK module path is:
|
||||
|
||||
```text
|
||||
git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_go
|
||||
```
|
||||
|
||||
Generated files live at:
|
||||
|
||||
```text
|
||||
yoresee_doc/v1/yoresee_doc.pb.go
|
||||
yoresee_doc/v1/yoresee_doc_grpc.pb.go
|
||||
```
|
||||
|
||||
The protobuf `go_package` is changed to:
|
||||
|
||||
```text
|
||||
git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_go/yoresee_doc/v1;yoreseedocpb
|
||||
```
|
||||
|
||||
The initial SDK release is `v0.1.0`. `backend` and `collab-go` pin this
|
||||
version instead of depending on the moving `master` branch.
|
||||
|
||||
### Node.js
|
||||
|
||||
The package name is `@yoresee-doc/sdk-node`, installed from:
|
||||
|
||||
```text
|
||||
git+ssh://git@git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_node.git#v0.1.0
|
||||
```
|
||||
|
||||
Generated output is split by runtime:
|
||||
|
||||
```text
|
||||
esm/yoresee_doc/v1/yoresee_doc_pb.js
|
||||
esm/yoresee_doc/v1/yoresee_doc_connect.js
|
||||
cjs/yoresee_doc/v1/yoresee_doc_pb.js
|
||||
cjs/yoresee_doc/v1/yoresee_doc_grpc_pb.js
|
||||
```
|
||||
|
||||
The package uses conditional exports and explicit `esm/*` and `cjs/*`
|
||||
subpaths. The `cjs/` directory declares CommonJS module semantics so the
|
||||
root package can remain ESM-compatible.
|
||||
|
||||
Service import contracts are:
|
||||
|
||||
- `frontend`: `@yoresee-doc/sdk-node/esm/yoresee_doc/v1/...`
|
||||
- `collab`: `@yoresee-doc/sdk-node/cjs/yoresee_doc/v1/...`
|
||||
|
||||
Runtime dependencies for both generated formats are declared by the SDK:
|
||||
`@bufbuild/protobuf`, `@connectrpc/connect`, `@grpc/grpc-js`, and
|
||||
`google-protobuf`.
|
||||
|
||||
## Generation and Repository Boundaries
|
||||
|
||||
The generated files are committed to the SDK repositories because they are the
|
||||
published dependency artifacts. The source proto remains in the existing
|
||||
`proto` repository and is not duplicated into the SDK repositories.
|
||||
|
||||
Generation for this initial migration is performed from the checked-out proto
|
||||
source using the existing installed toolchains. The migration does not alter
|
||||
the existing project generation scripts. Each SDK README records the source
|
||||
proto commit and the generator versions used for the artifacts.
|
||||
|
||||
## Service Migration
|
||||
|
||||
`backend` and `collab-go` replace local generated-package imports with the Go
|
||||
SDK import path and add the pinned Gitea module dependency. The services set
|
||||
`GOPRIVATE` in their build environment documentation where required by the
|
||||
private module.
|
||||
|
||||
`frontend` and `collab` add the pinned Git dependency and replace aliases or
|
||||
relative paths that point to local generated files with the Node SDK exports.
|
||||
|
||||
No service behavior or protobuf message/service definitions change.
|
||||
|
||||
## Verification
|
||||
|
||||
The implementation is accepted only after all of the following checks pass:
|
||||
|
||||
- Go SDK generated package compiles and its module resolves at `v0.1.0`.
|
||||
- Node SDK can be installed from the Gitea tag and both module formats load.
|
||||
- `backend` and `collab-go` compile with the remote SDK dependency.
|
||||
- `frontend` production build resolves the ESM/Connect exports.
|
||||
- `collab` can load the CJS protobuf and gRPC exports.
|
||||
- SDK repositories have clean commits pushed to `master`, with `v0.1.0`
|
||||
tags.
|
||||
|
||||
## Risks and Rollback
|
||||
|
||||
- Private Gitea dependencies require read access from developer and Docker/CI
|
||||
environments. A failed authenticated fetch is an environment issue, not a
|
||||
protobuf generation issue.
|
||||
- The old local generation remains redundant and may continue to fail because
|
||||
its existing buf templates are outside this migration scope.
|
||||
- Rollback consists of reverting service dependency/import changes and the
|
||||
protobuf `go_package` change; SDK repositories remain harmless additive
|
||||
artifacts.
|
||||
Reference in New Issue
Block a user