Repository navigation
Open
Labels
area:platformSDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management.SDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management.topic:apiPublic APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards.Public APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards.topic:documentationArchitecture docs, READMEs, project website updates, and automated documentation generation.Architecture docs, READMEs, project website updates, and automated documentation generation.topic:dxMaking OpenShell easy to contribute to for humans and agents.Making OpenShell easy to contribute to for humans and agents.topic:testingUnit, integration, regression, conformance, E2E tests, coverage, flakes, and test infrastructure.Unit, integration, regression, conformance, E2E tests, coverage, flakes, and test infrastructure.
Description
On the July 14, 2026 community call the issue of new SDK adoption came up. Presently we don't have any kind of standard for adopting new SDKs.
It would be good if we had a document which declared the standard that must be met before an SDK is adopted.
I think the standard should include:
- Local dev environment support. This may be obvious, but it means making sure
miseorNixorbazelor whichever tooling we use for specifying the environment incorporates support for the SDK's language - linting and unit testing of the SDK
- hooking that linting and unit testing into the automated testing mechanism (presently
mise) - Adding that to CI, probably as its own task/action
- Documenting the available features of the SDK. During development the SDK may not support everything, but even after release there may be some inherent limitations of the SDK, or new features of OpenShell not yet supported by it, so those should be documented. I have in mind how Gateway API does it.
It would be extremely valuable if we had a conformance testing environment that we could run SDK tests against; a predefined set of actions that the SDK will exercise to show it conforms to some level of OpenShell support. We don't have that yet, but if we did have that, the standard would include running that conformance test.
Metadata
Metadata
Assignees
Labels
area:platformSDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management.SDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management.topic:apiPublic APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards.Public APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards.topic:documentationArchitecture docs, READMEs, project website updates, and automated documentation generation.Architecture docs, READMEs, project website updates, and automated documentation generation.topic:dxMaking OpenShell easy to contribute to for humans and agents.Making OpenShell easy to contribute to for humans and agents.topic:testingUnit, integration, regression, conformance, E2E tests, coverage, flakes, and test infrastructure.Unit, integration, regression, conformance, E2E tests, coverage, flakes, and test infrastructure.
Activity
rhuss commentedon Jul 16, 2026
Do we want to specify a minimum bar for the unit test code coverage ? codecov has a decent support for many languages and can be integrated as a CI gate to ensure that new PRs don't drop the coverage below a threshold.
I've used it e.g. for the golang SDK, here's an example --> rhuss/openshell-sdk-go#27 (comment)
No custom CI integration needed (and codecov is free for open source projects)
rhuss commentedon Jul 16, 2026
+1 and the RFC proposal above proposes a 3-level taxonomy for a coarse grained categorisation so that user easily see how deep the SDK goes. Could be more or less than 3 levels, but I think keeping it simple makes it easier (its not an exact science anyway)
github-actions commentedon Jul 31, 2026
This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.
github-actions commentedon Nov 11, 2026
This issue has had no activity for 28 days and is now marked stale. It may be closed in 14 days if there is no further activity. Comment or remove the state:stale label to keep it open.
rhuss commentedon Nov 11, 2026
This still seems useful after moving Go and Python into their own repositories, though the scope has changed. Both SDKs now have development checks, core-version tracking, and E2E workflows, so we can document the baseline established by that experience.
I suggest keeping this issue for a short shared SDK support guide covering ownership, supported features and gateway versions, reproducible checks, binding freshness, and real-gateway testing. Each SDK repository would own its implementation and CI; shared CI conventions are already tracked in ai-openshell/sdk-python#11.
We previously deferred the scorecard proposal in #2292, and the conformance RFC #3238 was closed after the repository moves. I would leave formal tiers and certification for a demonstrated need, and use this issue to make current expectations clear.