Skip to content

Upstream PR Preparation [Spec] - #30

Open
rhuss wants to merge 12 commits into
mainfrom
019-upstream-pr
Open

Upstream PR Preparation [Spec]#30
rhuss wants to merge 12 commits into
mainfrom
019-upstream-pr

Conversation

@rhuss

@rhuss rhuss commented Jul 11, 2026

Copy link
Copy Markdown
Owner

Why This Change

The OpenShell Go SDK has been developed in a standalone repository
(rhuss/openshell-sdk-go) providing typed gRPC clients for the gateway
and edge APIs, in-memory fakes for testing, and OIDC authentication.
Upstream issue #2044
requests contributing this SDK into the NVIDIA/OpenShell monorepo under
sdk/go/. Without this contribution, Go developers must discover and
depend on a personal fork rather than the official project.

What Changes

The Go SDK source is relocated into the upstream repo at sdk/go/ with
its module path rewritten from github.com/rhuss/openshell-sdk-go to
github.com/NVIDIA/OpenShell/sdk/go. The 4,649-LOC oshell TUI example
is extracted to a separate repository (rhuss/openshell-examples) to
keep the PR focused on library code. Four concise Fern MDX documentation
pages are added under docs/sdks/go/. A Go CI job and proto freshness
check are added to the existing branch-checks workflow. The PR is
delivered as a single squashed draft commit referencing issue #2044.

How It Works

The implementation proceeds in three phases:

  1. Module path migration: Mechanical sed replacement of the module
    path in go.mod, all .go files, and the mise proto generation
    scripts. Proto bindings are regenerated under the new module. Build
    and test verification confirms zero regressions.

  2. Documentation and CI: Fern MDX pages (getting-started, architecture,
    error-handling, authentication) are created under docs/sdks/go/ and
    wired into the docs navigation. A tasks/go.toml mise task wraps
    proto generation for the monorepo context. A Go job is added to
    branch-checks.yml following the existing Rust/Python pattern
    (checkout, mise install, lint, build, test, proto:check).

  3. PR assembly: Internal artifacts (brainstorms, spec-kit config,
    Claude Code config) are excluded. Design specs are included under
    sdk/go/specs/ with an explicit question to upstream maintainers
    about whether to retain them. All changes are squashed into a single
    DCO-signed commit.


Important

Review Guide contains the full review guidance: key decisions, scope boundaries, areas needing attention, and review checklist.

This PR contains the specification artifacts for Upstream PR Preparation. Implementation follows after spec approval.

Assisted-By: 🤖 Claude Code


Open in Devin Review

Summary by CodeRabbit

  • Documentation
    • Added planning and research documentation for upstreaming the Go SDK.
    • Added guides, checklists, data models, implementation plans, and task breakdowns for the upstream contribution.
    • Added authentication and schema documentation proposals.
    • Updated project overview tracking and open discussion topics.
  • Planning
    • Documented module migration, example extraction, SDK documentation, proto generation, CI validation, and draft pull request preparation.

rhuss added 9 commits July 11, 2026 07:50
Assisted-By: 🤖 Claude Code
Assisted-By: 🤖 Claude Code
Assisted-By: 🤖 Claude Code
Assisted-By: 🤖 Claude Code
Assisted-By: 🤖 Claude Code
Assisted-By: 🤖 Claude Code
@coderabbitai

coderabbitai Bot commented Jul 11, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@rhuss, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 26 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f539e6f0-570e-4abe-8a64-3e54dde4288c

📥 Commits

Reviewing files that changed from the base of the PR and between a72f4a6 and e7e7861.

📒 Files selected for processing (7)
  • brainstorm/00-overview.md
  • specs/019-upstream-pr/checklists/requirements.md
  • specs/019-upstream-pr/plan.md
  • specs/019-upstream-pr/quickstart.md
  • specs/019-upstream-pr/research.md
  • specs/019-upstream-pr/spec.md
  • specs/019-upstream-pr/tasks.md
📝 Walkthrough

Walkthrough

Added planning and specification documentation for upstreaming the Go SDK into the OpenShell monorepo, including repository mapping, module migration, examples extraction, Fern docs, CI automation, execution tasks, verification steps, and review checklists.

Changes

Upstream PR planning

Layer / File(s) Summary
Planning index and topic briefs
CLAUDE.md, brainstorm/00-overview.md, brainstorm/022-auth-guide.md, brainstorm/023-schema-docs.md, brainstorm/024-upstream-pr.md
Updated planning status and added brainstorm documents for authentication, schema documentation, and upstream PR preparation.
Upstream PR specification and design
specs/019-upstream-pr/spec.md, specs/019-upstream-pr/data-model.md, specs/019-upstream-pr/research.md
Defined requirements, repository mapping, module-path migration, examples extraction, Fern documentation, CI integration, exclusions, and validation criteria.
Execution workflow and task decomposition
specs/019-upstream-pr/plan.md, specs/019-upstream-pr/quickstart.md, specs/019-upstream-pr/tasks.md
Added implementation phases, prerequisites, task dependencies, parallelization guidance, commands, and verification steps.
Review guide and quality gates
specs/019-upstream-pr/REVIEWERS.md, specs/019-upstream-pr/checklists/requirements.md
Added an upstream review guide and completed specification quality checklist.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

  • Issue 28 — The authentication guide brainstorm directly addresses the requested unified authentication documentation work.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title matches the core change: adding upstream PR preparation specification artifacts.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch 019-upstream-pr

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@codecov

codecov Bot commented Jul 11, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.63%. Comparing base (580d763) to head (e7e7861).

Additional details and impacted files
@@            Coverage Diff             @@
##             main      #30      +/-   ##
==========================================
+ Coverage   88.51%   88.63%   +0.12%     
==========================================
  Files          70       70              
  Lines        4163     4163              
==========================================
+ Hits         3685     3690       +5     
+ Misses        330      325       -5     
  Partials      148      148              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

devin-ai-integration[bot]

This comment was marked as resolved.

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

rhuss added 2 commits July 11, 2026 11:25
Applied fixes from bot review comments:
- Comment #3563837973: Fix DCO sign-off name spelling (Huss -> Huß) in T031
- Comment #3563844937: Ensure replace directive removed before pushing examples repo in T016/T018
- Comment #3563839677: Use portable sed -i.bak syntax in quickstart.md
- Comment #3563844934: Use portable sed -i.bak syntax in quickstart.md (duplicate)
- Comment #3563844927: Downgrade gate result from PASS to CHECK (secret scan pending)
- Comment #3563839654: Uncheck inapplicable checklist items (spec is inherently technical)
- Comment #3563839661: Uncheck technology-agnostic success criteria checklist item
- Comment #3563839667: Uncheck no-implementation-details checklist item

Assisted-By: 🤖 Claude Code
Applied fixes from local CodeRabbit review (remote was rate-limited):
- Clarify docs/ exclusion scope in FR-011 (mdbook only, not Fern MDX)
- Add proto:gen step to quickstart.md before go mod tidy
- Align proto task names in research.md (go:proto vs go:proto:check)
- Clarify examples repo bootstrap strategy in T018

Assisted-By: 🤖 Claude Code
devin-ai-integration[bot]

This comment was marked as resolved.

- Comment #3563869706: Mark brainstorm 024 as specified with spec 019

Assisted-By: 🤖 Claude Code

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Comment thread specs/019-upstream-pr/research.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants