Skip to content

docs(windows): route main documentation to the Windows release branch - #4758

Open
shailendra-nv wants to merge 5 commits into
mainfrom
docs/4756-windows-release-references/shailendra-nv
Open

shailendra-nv wants to merge 5 commits into
mainfrom
docs/4756-windows-release-references/shailendra-nv

Conversation

@shailendra-nv

@shailendra-nv shailendra-nv commented Oct 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Direct readers of main's documentation to the maintained native Windows implementation on windows. This PR is based on main and changes documentation only, keeping Windows implementation and releases on their own branch.

Merge the companion Windows documentation PR #4757 first so links to its new WINDOWS.md resolve.

Related Issue

Closes #4756.

Companion: #4757 targets windows and closes #4755. Related MXC implementation-detail documentation work is in #4646.

The author has verified MAINTAIN access; the issue currently has no state:accepted label.

Changes

  • Add a top-level Windows guide and update README, CONTRIBUTING, TESTING, CI, and AGENTS.
  • Pin Windows source, build, configuration, and runtime links to windows, including from published docs on main.
  • Distinguish native MXC from WSL, main's installer/release artifacts, and older MXC source snapshots retained on main.
  • Refresh Windows contributor guidance from the Windows branch, require a Windows-based checkout, and include E2E in both full-validation paths with an exit-code check after every task.
  • Preserve main's code and unrelated documentation. All 14 changed files are Markdown/MDX.

Release Notes

Native Windows documentation now identifies windows as its implementation and release branch and explains the current build and runtime limitations.

Testing

  • Markdown lint: 161 files, zero errors; repeated by the commit hook. Both changed contributor-skill files also passed direct lint with the repository rules.
  • PowerShell validation examples: 96 execution cases across both documents, x64/ARM64 paths, and Windows PowerShell 5.1/PowerShell 7, using a native mock executable to simulate success, failure at every task, and incomplete E2E coverage. Verified that execution stops immediately after each failed task. Thirty-two baseline checks reproduced masked failures; all six PowerShell blocks parsed in both versions.
  • Skill YAML metadata, local links, and all 14 referenced Windows tasks checked against the live Windows branch.
  • Mermaid validation: 210 files scanned, all diagrams valid.
  • SPDX validation: 1,300 files checked, all headers valid.
  • Documentation navigation checker: every page URL matches its path.
  • Fern 5.112.0 validation: zero errors and three existing warnings. The gateway configuration MDX parse warning also reproduced with that file restored to its unchanged main baseline; the other warnings cover unauthenticated redirect checking and theme contrast.
  • Added repository links and anchors checked against the corresponding checkout; git diff --check passed.
  • Full mise run pre-commit was attempted again but could not complete because Rust toolchain and Python/TypeScript dependency downloads were unavailable in this environment. Scoped contributor-guidance checks passed, including all 20 immediate exit-code checks. A temporary documentation-only commit hook passed; the installed repository hook was unchanged.
  • Runtime unit/E2E tests are not applicable. No runtime or build implementation changed.

Checklist

  • Follows Conventional Commits.
  • Commits are signed off (DCO).
  • Relevant architecture and published documentation updated.

Signed-off-by: Shailendra Singh <shailendras@nvidia.com>
@copy-pr-bot

copy-pr-bot Bot commented Oct 20, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-23T16:38:22.973152Z 14b86a1 New commits
🔒 Security Review ✅ Completed 2026-10-23T16:37:10.997119Z 14b86a1 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c9142ea7d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread .agents/skills/build-openshell-mxc-windows/reference.md
Signed-off-by: Shailendra Singh <shailendras@nvidia.com>

@drew drew left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Let's try and keep docs short and consistent.

Comment thread docs/about/architecture.mdx Outdated
Comment on lines +11 to +18
Native Windows has a separate implementation on the
[`windows` development and release branch](https://github.com/NVIDIA/OpenShell/tree/windows).
It pairs a host supervisor with an MXC ProcessContainer boundary. See the
[Windows architecture and limitations](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md#runtime-and-current-limits)
before applying the guarantees below to that implementation. Exclusive
supervisor-mediated egress and live access revocation are not yet verified
for MXC. These Windows links remain on `windows` when this page is published
from `main`.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This doesn't belong at the top of the architecture page! Please remove.

@shailendra-nv shailendra-nv Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Removed the Windows paragraph above the diagram.

Comment thread docs/about/installation.mdx Outdated
Comment thread docs/about/support-matrix.mdx Outdated
Comment thread docs/about/support-matrix.mdx Outdated
Comment thread docs/how-it-works/gateways/configuration.mdx Outdated
Comment thread docs/CONTRIBUTING.mdx Outdated
Comment on lines +11 to +16
Native Windows implementation and releases remain on the
[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows).
Shared documentation can also publish from `main`. Link Windows-only source,
tasks, and runtime instructions explicitly to `blob/windows/` or `tree/windows/`
so those links remain valid from either branch. Do not describe `main` release
artifacts or `install.sh` as the native Windows distribution path.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Remove

@shailendra-nv shailendra-nv Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Removed the Windows-specific paragraph.

Comment thread AGENTS.md Outdated
Comment thread SECURITY.md Outdated
Comment thread STYLEGUIDE.md Outdated
Comment thread TESTING.md Outdated
Signed-off-by: Shailendra Singh <shailendras@nvidia.com>

shailendra-nv commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator Author

Thanks for the feedback. The follow-up is pushed in 960d14ea. It trims the repeated Windows callouts, adds dedicated Windows sections, and restores the gateway example with current settings.

The scoped documentation checks passed. The broad pre-commit task could not complete because Rust/Python dependency downloads are blocked in this environment; the documentation-only commit hook passed.

@chatgpt-codex-connector chatgpt-codex-connector Bot 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 960d14ea54

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread .agents/skills/build-openshell-mxc-windows/SKILL.md
Signed-off-by: Shailendra Singh <shailendras@nvidia.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a11a8a2ec2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread .agents/skills/build-openshell-mxc-windows/SKILL.md
Signed-off-by: Shailendra Singh <shailendras@nvidia.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 14b86a1289

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/how-it-works/gateways/configuration.mdx

This branch has not been deployed

No deployments
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.

docs: route main documentation to the Windows release branch docs(windows): establish branch-specific top-level Windows guidance

2 participants