Skip to content

Router that virtually distributes inference across connected devices in the home.

Go

Point contributor tooling at the pull request workflow

Tervee8cc440a7ac0
diff --git a/.cursor/rules/commit-sign-off.mdc b/.cursor/rules/commit-sign-off.mdc
index 4306308..f3943b4 100644
--- a/.cursor/rules/commit-sign-off.mdc
+++ b/.cursor/rules/commit-sign-off.mdc
@@ -51,10 +51,8 @@ original **author**. That produces exactly the mismatch the check rejects, and
it certifies work that is not yours.
Cherry-pick without `-s` and keep whatever trailer the original author wrote.
-This matters most when importing community commits from GitHub, which is the one
-workstream that replays another person's commits — see workstream C in
-`.cursor/skills/pair-repo-sync/SKILL.md`. Publishing to GitHub does not replay
-commits at all; it commits a cut tree, so no sign-off decision arises there.
+This matters most when replaying a contributor's commits — backporting a fix, or
+rebuilding a branch on a new base.
## Exemptions
@@ -68,4 +66,3 @@ commits at all; it commits a cut tree, so no sign-off decision arises there.
- Contributor-facing policy and the full DCO text: `CONTRIBUTING.md`.
- Branch and push workflow: `no-push-to-main.mdc`.
-- Cross-remote replay: `repository-sync.mdc`.
diff --git a/.cursor/rules/no-push-to-main.mdc b/.cursor/rules/no-push-to-main.mdc
index cb5070f..538db19 100644
--- a/.cursor/rules/no-push-to-main.mdc
+++ b/.cursor/rules/no-push-to-main.mdc
@@ -1,5 +1,5 @@
---
-description: Never push directly to main; always use a feature branch and GitLab MR
+description: Never push directly to a shared branch; always use a feature branch and a pull request
alwaysApply: true
---
<!--
@@ -7,48 +7,45 @@ SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All
SPDX-License-Identifier: Apache-2.0
-->
-# Never push to main
+# Never push to a shared branch
-Agents must **never** push to `main` (or `master`) on any remote — including
-`gitlab` and `origin`.
+Agents must **never** push directly to `develop` or `main` on `origin`.
+`develop` is the integration branch; `main` carries released source.
## Required workflow
1. Create or switch to a **feature branch** (never commit intended work only on
- `main` if it will be pushed).
+ a shared branch if it will be pushed).
2. Commit on that branch with `git commit -s` — every commit needs a DCO
sign-off trailer (see `commit-sign-off.mdc`).
-3. Push the **feature branch** only: `git push -u gitlab HEAD` or
- `git push -u gitlab <branch-name>`.
-4. Open a **GitLab merge request** into `main`. Do not merge unless the user
+3. Push the **feature branch** only: `git push -u origin HEAD` or
+ `git push -u origin <branch-name>`.
+4. Open a **pull request** into `develop`. Do not merge unless the user
explicitly asks.
## Explicit bans
-- `git push … main`, `git push … HEAD:main`, or any refspec that updates
- `refs/heads/main` / `refs/heads/master` on a remote.
-- Force-pushing `main` / `master` unless the user **explicitly** requests that
+- `git push … develop`, `git push … main`, `git push … HEAD:develop`, or any
+ refspec that updates `refs/heads/develop` or `refs/heads/main` on a remote.
+- Force-pushing a shared branch unless the user **explicitly** requests that
exact force update in the current message (and even then, prefer
`--force-with-lease` and confirm the target SHA).
-- Treating “commit and push” as permission to push `main`. That phrase means
- push the **current feature branch**.
+- Treating “commit and push” as permission to push a shared branch. That phrase
+ means push the **current feature branch**.
-## If already on main locally
+## If already on a shared branch locally
-When the user asks to commit/push and `git branch --show-current` is `main`:
+When the user asks to commit/push and `git branch --show-current` is `develop`
+or `main`:
1. Create a feature branch from the commits (or before committing).
2. Push that branch.
-3. Point the user at an MR URL.
+3. Point the user at a pull request URL.
-Do **not** push `main` “just this once.”
+Do **not** push a shared branch “just this once.”
## Related
- Signing off each commit: `commit-sign-off.mdc`.
-- Dual-remote / public-cut rules: `repository-sync.mdc` and
- `.cursor/skills/pair-repo-sync/SKILL.md`.
-- Those rules already forbid pushing GitLab `main` to GitHub; this rule forbids
- pushing **to** GitLab `main` as well.
-- Filling the MR description / `pair-release-intent` block:
- `.cursor/skills/pair-gitlab-mr/SKILL.md`.
+- Filling the pull request description and the `pair-release-intent` block:
+ `.cursor/skills/pair-github-pr/SKILL.md`.
diff --git a/.cursor/rules/service-contracts.mdc b/.cursor/rules/service-contracts.mdc
index 3985fe2..dbbd1ba 100644
--- a/.cursor/rules/service-contracts.mdc
+++ b/.cursor/rules/service-contracts.mdc
@@ -65,19 +65,19 @@ npm run service-contracts:check
and `npm run typecheck`.
9. Commit `services/` and desktop integration edits together.
-## Version bumps depend on the remote
-
-On GitLab, declare bumps in the merge request `pair-release-intent:v1` block and
-leave `services/versions.json` and root `CHANGELOG.md` alone — `validate:release-intent`
-fails a hand edit without `<!-- pair-release-intent-allow-owned-files -->`, and
-`apply:release-intent` writes both files after merge. See
-`.cursor/skills/pair-gitlab-mr/SKILL.md` and `ci/release-intent/README.md`.
-
-GitHub has no such pipeline, and the cut deletes `ci/`, so a contributor there
-edits both files by hand. The public docs (`services/VERSIONING.md`,
-`services/readme.md`, `CONTRIBUTING.md`, `CHANGELOG.md`) describe the manual path
-as the default and must not mention internal release tooling, instruct readers to
-declare a release in a merge request, or point at `ci/release-intent/`.
+## Version bumps are declared in the pull request
+
+Declare bumps in the pull request `pair-release-intent:v1` block and leave
+`services/versions.json` alone — `release-intent-check.yml` fails a hand edit
+without `<!-- pair-release-intent-allow-owned-files -->`, and
+`release-intent-apply.yml` writes the file after merge. See
+`.cursor/skills/pair-github-pr/SKILL.md` and
+`scripts/release-intent/README.md`.
+
+A contributor working from a fork cannot run the apply workflow, so
+`services/VERSIONING.md`, `services/readme.md` and `CONTRIBUTING.md` describe
+editing `services/versions.json` by hand. Keep that path documented; reconcile
+the two during review rather than asking contributors to leave the file alone.
## Rules
diff --git a/.cursor/skills/pair-github-pr/SKILL.md b/.cursor/skills/pair-github-pr/SKILL.md
new file mode 100644
index 0000000..71bcb9c
--- /dev/null
+++ b/.cursor/skills/pair-github-pr/SKILL.md
@@ -0,0 +1,147 @@
+---
+name: pair-github-pr
+description: >-
+ Fills GitHub pull request descriptions with the required PAIR
+ pair-release-intent:v1 block so the release-intent check passes. Use when
+ opening, updating, or rewriting a PR description, when the user mentions
+ release intent, version bumps, changelog for a PR, or when a workflow run
+ fails on release-intent-check.
+---
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# PAIR pull request release intent
+
+`.github/workflows/release-intent-check.yml` runs on every pull request. A
+missing or malformed intent block **fails the check**. Agents that create or
+edit PR descriptions must include a valid block — do not invent a free-form
+changelog section.
+
+Canonical template (copy keys from here; keep the key set in sync with
+`services/versions.json`):
+
+`.github/PULL_REQUEST_TEMPLATE.md`
+
+SemVer meaning: `services/VERSIONING.md`. Operational detail (truncation,
+component add/remove): `scripts/release-intent/README.md`.
+
+## When opening or updating a pull request
+
+1. Push a **feature branch** only (never `develop` or `main` — see
+ `no-push-to-main.mdc`).
+2. Build the description from the template structure: **PAIR release intent
+ fence first** (truncation-safe), then Summary → Test plan.
+3. Decide release vs no-release (below).
+4. **Do not** edit `services/versions.json` in the pull request unless you also
+ add `<!-- pair-release-intent-allow-owned-files -->` (bootstrap/hotfix, or
+ component add/remove). `desktop/package.json` `version` is a manual
+ release-cut carve-out and is not part of this block.
+5. Before pushing the description, validate locally:
+
+```bash
+# Write the PR body to a file, then:
+python3 scripts/release-intent/validate_pr.py \
+ --description-file /tmp/pr-description.md \
+ --skip-owned-files-check
+```
+
+In the workflow run, drop `--skip-owned-files-check` (CI enforces owned paths).
+
+## No release (most pull requests)
+
+Every bump value is `none`. Changelog title and body are exactly `n/a`.
+
+Use a Markdown bullet list for bumps (`- key: value`) so the rendered pull
+request stays one key per line without a code fence.
+
+```markdown
+<!-- pair-release-intent:v1 -->
+### Changelog title
+n/a
+
+### Changelog body
+n/a
+
+### Bumps
+- product: none
+- nvpair-cluster-manager: none
+- nvpair-engine-manager: none
+- nvpair-errors: none
+- nvpair-job-scheduler: none
+- nvpair-manual-nodes: none
+- nvpair-node-info: none
+- nvpair-node-scanner: none
+- nvpair-node-settings: none
+- nvpair-proxy: none
+- nvpair-tui: none
+- nvpair-ui-broker: none
+- nvpair-workload-manager: none
+<!-- /pair-release-intent:v1 -->
+```
+
+If `services/versions.json` gained or lost a component, edit that file in the
+pull request with `<!-- pair-release-intent-allow-owned-files -->`, and
+regenerate the bump key list (`product` + sorted component names). Extra or
+missing keys fail the check.
+
+## Shipping a product release
+
+1. Set each touched component to `patch`, `minor`, or `major` (SemVer meaning
+ in `VERSIONING.md`). Untouched components stay `none`.
+2. Set `product` to a severity **≥** the highest component bump. UI-only
+ product notes may bump `product` while all components stay `none`.
+3. Replace changelog title/body with real **user-facing** prose (not `n/a`).
+ Prefer bullets in the body.
+4. Leave owned files alone — `release-intent-apply.yml` writes them after the
+ pull request merges.
+
+Example (engine-manager feature + product minor):
+
+```markdown
+<!-- pair-release-intent:v1 -->
+### Changelog title
+Model downloads show live progress
+
+### Changelog body
+- Pulling a model on this machine now shows a live percentage instead of a spinner.
+
+### Bumps
+- product: minor
+- nvpair-cluster-manager: none
+- nvpair-engine-manager: minor
+- nvpair-errors: none
+- nvpair-job-scheduler: none
+- nvpair-manual-nodes: none
+- nvpair-node-info: none
+- nvpair-node-scanner: none
+- nvpair-node-settings: none
+- nvpair-proxy: none
+- nvpair-tui: none
+- nvpair-ui-broker: none
+- nvpair-workload-manager: none
+<!-- /pair-release-intent:v1 -->
+```
+
+## Hard format rules (the check fails otherwise)
+
+- Exact fences: `<!-- pair-release-intent:v1 -->` … `<!-- /pair-release-intent:v1 -->`
+- Exact headings: `### Changelog title`, `### Changelog body`, `### Bumps`
+- Enums only: `none` | `patch` | `minor` | `major` (lowercase)
+- One bullet per key: `- key: value` (plain `key: value` still accepted)
+- HTML/`#` comment lines inside the intent block are allowed and ignored
+- Any non-`none` bump ⇒ real changelog (not `n/a`)
+- All bumps `none` ⇒ both changelog fields exactly `n/a`
+
+## Fixing a failed release-intent check
+
+1. Read the workflow log (it prints the parse error).
+2. Edit the **pull request description** (not a new commit) unless owned files
+ were wrongly changed — then revert those file edits on the branch.
+3. Re-run the workflow if it does not re-run on description-only edits.
+
+## Out of scope
+
+- Do not put internal issue identifiers or private tracker URLs in the
+ changelog body. Describe user-visible behavior instead.
diff --git a/desktop/README.md b/desktop/README.md
index cadcbc7..cf96f6c 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -52,7 +52,7 @@ npm test # unit tests
npm run service-contracts:check # this app still agrees with ../services
```
-Run all four before opening a merge request. `npm run format` applies formatting
+Run all four before opening a pull request. `npm run format` applies formatting
rather than just reporting it.
### While you are editing
diff --git a/scripts/spdx-headers.mjs b/scripts/spdx-headers.mjs
index 5a293aa..3b1bc54 100644
--- a/scripts/spdx-headers.mjs
+++ b/scripts/spdx-headers.mjs
@@ -155,7 +155,6 @@ const SKIPPED_PATHS = [
['desktop/docs/services-api.md', 'generated by npm run service-contracts:write'],
['desktop/src/ui/lib/kaizen-ui-foundations/', 'vendored Kaizen UI Foundations CSS'],
['.github/PULL_REQUEST_TEMPLATE.md', 'copied verbatim into pull request descriptions'],
- ['.gitlab/merge_request_templates/', 'copied verbatim into merge request descriptions'],
['scripts/collectlogs/testdata/', 'log fixtures the sanitizer tests compare byte for byte'],
]
diff --git a/services/readme.md b/services/readme.md
index 84a9421..1a3f1b8 100644
--- a/services/readme.md
+++ b/services/readme.md
@@ -206,7 +206,7 @@ cd tests
go test ./...
```
-Expect this to take a few minutes. Run it before opening a merge request, and
+Expect this to take a few minutes. Run it before opening a pull request, and
after any change to a JSON-RPC method, payload, or notification.
### Tests that skip themselves