From 170244b72e6dcffc67b5fd87af48f2f36a57292d Mon Sep 17 00:00:00 2001 From: Vladimir Date: Wed, 19 Aug 2026 14:47:54 +0800 Subject: [PATCH] Add GitHub issue forms, a light PR template, and an Alpha banner. Why: Strangers landing on the public repo had no install-failure, bug, or feature form, and no pull-request checklist. The Alpha, macOS, and Xcode limits were easy to miss on the first screen. Changed: Issue forms now cover install failure, bug, and feature. The chooser disables blank issues and points security reports at GitHub Security Advisories. The pull-request template is a public-patch checklist and does not require agent:context or a task session directory. README, getting-started, CONTRIBUTING, and status state the Alpha banner and link the issue forms. Specs and the specs manifest record the new .github community paths. Front-door tests pin the forms, the PR template, and the banner. Verification: npm run agent:verify -- --profile spec-only --paths .agents/manifests/specs.yaml,.github/ISSUE_TEMPLATE/config.yml,.github/ISSUE_TEMPLATE/install-failure.yml,.github/ISSUE_TEMPLATE/bug.yml,.github/ISSUE_TEMPLATE/feature.yml,.github/pull_request_template.md,README.md,CONTRIBUTING.md,docs/getting-started.md,docs/status.md,docs/test/front-door.test.mjs,spec/project-structure.md,spec/README.md,spec/build-and-test.md --session-dir task-sessions/20260819-github-community-hygiene node --test docs/test/front-door.test.mjs npm run verify:public-surface Affected: .agents/manifests/specs.yaml .github/ISSUE_TEMPLATE/config.yml .github/ISSUE_TEMPLATE/install-failure.yml .github/ISSUE_TEMPLATE/bug.yml .github/ISSUE_TEMPLATE/feature.yml .github/pull_request_template.md CONTRIBUTING.md README.md docs/getting-started.md docs/status.md docs/test/front-door.test.mjs spec/README.md spec/build-and-test.md spec/project-structure.md Refs: https://github.com/fiveonecode/simulator-broker spec/project-structure.md Session: task-sessions/20260819-github-community-hygiene --- .agents/manifests/specs.yaml | 4 ++ .github/ISSUE_TEMPLATE/bug.yml | 74 +++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 +++ .github/ISSUE_TEMPLATE/feature.yml | 52 ++++++++++++++ .github/ISSUE_TEMPLATE/install-failure.yml | 82 ++++++++++++++++++++++ .github/pull_request_template.md | 16 +++++ CONTRIBUTING.md | 8 +++ README.md | 6 +- docs/getting-started.md | 10 +++ docs/status.md | 3 +- docs/test/front-door.test.mjs | 52 ++++++++++++++ spec/README.md | 2 + spec/build-and-test.md | 3 + spec/project-structure.md | 3 + 14 files changed, 321 insertions(+), 2 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature.yml create mode 100644 .github/ISSUE_TEMPLATE/install-failure.yml create mode 100644 .github/pull_request_template.md diff --git a/.agents/manifests/specs.yaml b/.agents/manifests/specs.yaml index b1035a6..70b67dc 100644 --- a/.agents/manifests/specs.yaml +++ b/.agents/manifests/specs.yaml @@ -1,5 +1,7 @@ id: specs globs: + - .github/ISSUE_TEMPLATE/** + - .github/pull_request_template.md - .github/workflows/** - .gitignore - CHANGELOG.md @@ -27,6 +29,8 @@ primary_specs: verification_profile: spec-only commit_required: true allowed_paths: + - .github/ISSUE_TEMPLATE/** + - .github/pull_request_template.md - .github/workflows/** - .gitignore - CHANGELOG.md diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..018596d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,74 @@ +name: Bug +description: Something already documented does not behave as specified. +title: "[Bug]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Simulator Broker is **Alpha**, **macOS-only**, and needs **Xcode** to + create or run iOS Simulators. Interfaces can change. + + Use the install-failure form if `simbroker` never became usable. + Do not paste credentials, private home paths, customer data, or + live lease files. + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Which command, app pane, or script misbehaved? + validations: + required: true + - type: textarea + id: expected + attributes: + label: What should have happened? + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + placeholder: | + 1. Run `simbroker …` + 2. … + 3. See the error + validations: + required: true + - type: input + id: version + attributes: + label: Version or commit + description: Tagged Alpha such as 0.1.0-alpha.1, or a short commit SHA. + placeholder: 0.1.0-alpha.1 + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + description: macOS, Xcode, and Node.js versions. No private paths. + value: | + - macOS: + - Xcode: + - Node.js: + validations: + required: true + - type: textarea + id: logs + attributes: + label: Redacted logs + render: shell + validations: + required: false + - type: checkboxes + id: confirm + attributes: + label: Before submitting + options: + - label: I understand this is Alpha, macOS-only, and requires Xcode. + required: true + - label: I searched existing issues and did not find a duplicate. + required: true + - label: I removed credentials, private paths, and customer data from this report. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..36e61b5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security advisory + url: https://github.com/fiveonecode/simulator-broker/security/advisories/new + about: Report a vulnerability privately. Do not open a public issue. + - name: Getting started + url: https://github.com/fiveonecode/simulator-broker/blob/main/docs/getting-started.md + about: Install and first-run help. This project is Alpha, macOS-only, and needs Xcode. diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000..655a8f3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,52 @@ +name: Feature +description: Propose a change that is not already in the Alpha contract. +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Simulator Broker is **Alpha**, **macOS-only**, and needs **Xcode**. + It is maintenance-only infrastructure. There is no Homebrew formula, + notarized app, or npm package yet. + + Maintainers may decline requests that add a feature, commercialization, + or UX roadmap. + - type: textarea + id: problem + attributes: + label: What problem are you hitting? + description: Describe the gap a stranger hits today. Not a solution yet. + validations: + required: true + - type: textarea + id: proposal + attributes: + label: What should change? + description: A concrete, bounded change. Link docs or specs if you have them. + validations: + required: true + - type: dropdown + id: surface + attributes: + label: Which surface is this about? + options: + - CLI / broker-core + - Local brokerd service + - macOS operator app + - Install or packaging + - Docs or contributor track + - Other + validations: + required: true + - type: checkboxes + id: confirm + attributes: + label: Before submitting + options: + - label: I understand this is Alpha, macOS-only, and requires Xcode. + required: true + - label: I searched existing issues and did not find a duplicate. + required: true + - label: This is not a security report. I will use a private advisory for vulnerabilities. + required: true diff --git a/.github/ISSUE_TEMPLATE/install-failure.yml b/.github/ISSUE_TEMPLATE/install-failure.yml new file mode 100644 index 0000000..7faaca5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/install-failure.yml @@ -0,0 +1,82 @@ +name: Install failure +description: The CLI, tarball, or local installer did not work on this Mac. +title: "[Install]: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Simulator Broker is **Alpha**, **macOS-only**, and needs **Xcode** to + create or run iOS Simulators. There is no Homebrew formula, notarized + app, or npm package yet. + + Do not paste credentials, private home paths, customer data, or + live lease files. Redact logs first. Security reports go through + [GitHub Security Advisories](https://github.com/fiveonecode/simulator-broker/security/advisories/new), + not a public issue. + - type: dropdown + id: install-path + attributes: + label: What install path did you use? + options: + - CLI-only (`bash scripts/install_local.sh --cli-only`) + - Contributor app + CLI (`npm run install:local`) + - Alpha CLI tarball from GitHub Releases + - Other (describe below) + validations: + required: true + - type: textarea + id: command + attributes: + label: Command that failed + description: Paste the exact command. Do not include private paths. + render: shell + validations: + required: true + - type: textarea + id: expected-actual + attributes: + label: Expected versus actual + description: What should have happened, and what happened instead? + validations: + required: true + - type: input + id: macos + attributes: + label: macOS version + placeholder: "15.6" + validations: + required: true + - type: input + id: xcode + attributes: + label: Xcode version + placeholder: "16.4" + validations: + required: true + - type: input + id: node + attributes: + label: Node.js version + placeholder: "20.19.0" + validations: + required: true + - type: textarea + id: logs + attributes: + label: Redacted logs + description: Paste only the relevant output. Strip home directories and secrets. + render: shell + validations: + required: false + - type: checkboxes + id: confirm + attributes: + label: Before submitting + options: + - label: I understand this is Alpha, macOS-only, and requires Xcode. + required: true + - label: I searched existing issues and did not find a duplicate. + required: true + - label: I removed credentials, private paths, and customer data from this report. + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..a071079 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,16 @@ +## What changed + + + +## How you verified + +A public patch uses Node.js 20 and the Node suites that match the change. +You do not need the agent harness or a task session directory. + +- [ ] `npm run test:broker-core` / `npm run test:client` / `npm run test:harness-adoption` as applicable, or I explained why a deterministic test is not available +- [ ] I did not commit private paths, credentials, generated Xcode projects, local broker state, or task-session artifacts + +## Notes + +This project is **Alpha**, **macOS-only**, and needs **Xcode** to talk to iOS +Simulators. See [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a21d52c..2cd0cfc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,11 @@ Thanks for taking the time to improve Simulator Broker. +This project is **Alpha**, **macOS-only**, and needs **Xcode** to create or run +iOS Simulators. Report install failures, bugs, and feature requests with the +[issue forms](https://github.com/fiveonecode/simulator-broker/issues/new/choose). +Look at issues labeled `good first issue` if you want a bounded starter task. + This page has two tracks: 1. **Public patches** — Node.js 20 and the Node test suites. You do not need @@ -38,6 +43,9 @@ and you do not need to create a task session directory. ### Pull requests +The pull-request template is a short public-patch checklist. It does not ask +for a harness session directory. + - Keep changes focused and reviewable. - Include tests or explain why a deterministic test is not available. - Keep private or local context out of committed files. diff --git a/README.md b/README.md index 0a6a466..4a8701c 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,10 @@ A local control plane so humans, AI agents, and CI jobs can share iOS Simulators on one Mac without stealing devices from each other. -**Status:** Alpha · macOS only · Xcode required +> **Alpha.** macOS only. Xcode is required to create or run iOS Simulators. +> Interfaces can change. There is no Homebrew formula, notarized app, or npm +> package yet. + [![Node tests](https://github.com/fiveonecode/simulator-broker/actions/workflows/ci.yml/badge.svg)](https://github.com/fiveonecode/simulator-broker/actions/workflows/ci.yml) Simulator Broker leases simulator aliases by *purpose* (for example @@ -97,6 +100,7 @@ casually on a machine whose simulator inventory you cannot afford to change. - [Getting started](docs/getting-started.md) — install, first-run, reinstall, and uninstall - [Concepts](docs/concepts.md) — host, project, purpose, lease, pin, and `brokerd` - [Current capabilities](docs/status.md) — what this Alpha already implements +- [Open an issue](https://github.com/fiveonecode/simulator-broker/issues/new/choose) — install failure, bug, or feature - [Harness integration](spec/harness-integration.md) — make a consumer repo broker-aware - [Sample consumer repo](examples/harness-adoption/sample-consumer-repo/README.md) diff --git a/docs/getting-started.md b/docs/getting-started.md index e75076d..57ab507 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -8,6 +8,10 @@ human-readable text by default; pass `--json` for machine-readable payloads. A small public patch follows the public-patches track in [CONTRIBUTING.md](../CONTRIBUTING.md); it does not require the agent harness. +> **Alpha.** macOS only. Xcode is required to create or run iOS Simulators. +> Interfaces can change. There is no Homebrew formula, notarized app, or npm +> package yet. + ## Prerequisites - macOS with Xcode and iOS Simulator support installed @@ -144,6 +148,12 @@ npm run package:distribution GitHub Releases attach the Alpha CLI tarball. A signed, notarized app is not published there yet. +## Report a problem + +Use the GitHub issue forms. Pick **Install failure**, **Bug**, or **Feature**. +Do not paste credentials, private home paths, or live lease files. Security +reports go through [SECURITY.md](../SECURITY.md), not a public issue. + ## What to read next - [Concepts](concepts.md) diff --git a/docs/status.md b/docs/status.md index e730212..f137ef1 100644 --- a/docs/status.md +++ b/docs/status.md @@ -27,6 +27,8 @@ This Alpha already includes: - tagged Alpha CLI tarball through `npm run package:cli` and GitHub Releases - public Node test CI on GitHub-hosted Ubuntu for broker-core, client, harness-adoption, and public-surface checks +- GitHub issue forms for install failure, bug, and feature, plus a light PR + template that does not require a harness session - local-debug packaging through `npm run package:local` - signed distribution packaging through `npm run package:distribution` - `simbroker project init` for `.simulator-broker/project.json` @@ -63,4 +65,3 @@ node client/bin/simbroker.mjs simulators boot --alias ui-1 ## Lower-priority public follow-through - Homebrew formula, notarized app, and npm package -- issue templates and starter issues diff --git a/docs/test/front-door.test.mjs b/docs/test/front-door.test.mjs index 7d4a97f..30c9e75 100644 --- a/docs/test/front-door.test.mjs +++ b/docs/test/front-door.test.mjs @@ -37,6 +37,7 @@ test("README first screen is a product front door, not an implementation changel assert.ok(screen.includes("Alpha")); assert.ok(screen.includes("macOS")); assert.ok(screen.includes("Xcode")); + assert.ok(screen.includes("> **Alpha.**"), "README first screen must use a visible Alpha banner"); assert.equal( screen.includes("a first extracted file-backed `broker-core` slice exists"), false, @@ -174,6 +175,57 @@ test("release workflow packages the CLI tarball on version tags", () => { assert.equal(release.includes("test:app"), false); }); +test("issue forms cover install failure, bug, and feature and state Alpha limits", () => { + const config = readRepoFile(".github/ISSUE_TEMPLATE/config.yml"); + const install = readRepoFile(".github/ISSUE_TEMPLATE/install-failure.yml"); + const bug = readRepoFile(".github/ISSUE_TEMPLATE/bug.yml"); + const feature = readRepoFile(".github/ISSUE_TEMPLATE/feature.yml"); + + assert.ok(config.includes("blank_issues_enabled: false")); + assert.ok(config.includes("security/advisories")); + assert.ok(install.includes("name: Install failure")); + assert.ok(bug.includes("name: Bug")); + assert.ok(feature.includes("name: Feature")); + assert.ok(install.includes("install_local.sh --cli-only")); + assert.ok(bug.includes("labels:")); + assert.ok(feature.includes("enhancement")); + for (const body of [install, bug, feature, config]) { + assert.ok(body.includes("Alpha"), "community forms must say Alpha"); + assert.ok(body.includes("macOS"), "community forms must say macOS"); + assert.ok(body.includes("Xcode"), "community forms must say Xcode"); + } +}); + +test("PR template is a public-patch checklist and does not require the harness", () => { + const template = readRepoFile(".github/pull_request_template.md"); + + assert.ok(template.includes("npm run test:broker-core")); + assert.ok(template.includes("npm run test:client")); + assert.ok(template.includes("npm run test:harness-adoption")); + assert.ok(template.includes("Alpha")); + assert.ok(template.includes("macOS")); + assert.ok(template.includes("Xcode")); + assert.equal(template.includes("agent:context"), false); + assert.equal(template.includes("agent:verify"), false); + assert.equal(template.includes("agent:complete"), false); + assert.equal(template.includes("session-dir"), false); + assert.equal(template.includes("$HOME/.codex"), false); +}); + +test("status and contributing point strangers at issue forms, not later-sequence work", () => { + const status = readRepoFile("docs/status.md"); + const contributing = readRepoFile("CONTRIBUTING.md"); + const gettingStarted = readRepoFile("docs/getting-started.md"); + const readme = readRepoFile("README.md"); + + assert.ok(status.includes("GitHub issue forms")); + assert.equal(status.includes("issue templates and starter issues"), false); + assert.ok(contributing.includes("issues/new/choose")); + assert.ok(contributing.includes("good first issue")); + assert.ok(gettingStarted.includes("Report a problem")); + assert.ok(readme.includes("issues/new/choose")); +}); + test("package_cli.sh writes a runnable CLI tarball without tests or the app", () => { const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), "simbroker-package-cli-")); const result = spawnSync("bash", [path.join(repoRoot, "scripts/package_cli.sh"), "--output-dir", outputDir], { diff --git a/spec/README.md b/spec/README.md index c716f2c..7d59b34 100644 --- a/spec/README.md +++ b/spec/README.md @@ -55,6 +55,8 @@ This repo exists to develop a reusable local simulator broker: - the published onboarding docs now distinguish CLI-only install, repo-local contributor app+CLI install, local-debug portable bundling, and signed distribution packaging; a new login shell should resolve `simbroker` after install without sourcing `env.sh` - `CONTRIBUTING.md` publishes a public-patch track (Node.js 20 and the Node test suites, no harness session) and a labeled maintainer/agent harness track; `agent:complete` enforcement is unchanged - tagged Alpha `0.1.0-alpha.1` publishes a CLI tarball from `scripts/package_cli.sh` and runs the Node test surface on GitHub-hosted Ubuntu CI; the macOS app suite is not on that job +- GitHub issue forms cover install failure, bug, and feature; the pull-request + template is a public-patch checklist and does not require a harness session - `host init --bootstrap-config` warns that it creates real Simulator devices before provisioning them - broker-aware sample consumer repo artifacts now cover manual human, interactive agent, unattended agent build-and-test, and CI patterns under `examples/harness-adoption/` - broker-aware build/test leases now support downstream process registration, memory ceiling containment, evidence bundles, and forced-abort cleanup for detached simulator-like processes diff --git a/spec/build-and-test.md b/spec/build-and-test.md index 3e111c7..4c88064 100644 --- a/spec/build-and-test.md +++ b/spec/build-and-test.md @@ -292,6 +292,9 @@ Add stronger profiles next for: - `bash scripts/install_local.sh --cli-only` installs the CLI runtime without invoking `xcodegen` or `xcodebuild` and without requiring an app bundle - `npm run package:cli` writes `artifacts/cli/simulator-broker--cli.tar.gz` plus a SHA-256 checksum and does not invoke XcodeGen or `xcodebuild` - `.github/workflows/ci.yml` runs the public Node suites on `ubuntu-latest` with a 30-minute budget and does not run `npm run test:app` +- `.github/ISSUE_TEMPLATE/` ships install-failure, bug, and feature forms, and + `.github/pull_request_template.md` is a public-patch checklist that does not + require `agent:context` or a task session directory - `host init --bootstrap-config` writes a warning that real Simulator devices will be created before it calls `simctl` create - `npm run test:install-smoke` proves a fresh-machine-style install can bootstrap host config, scaffold a repo, start the service, acquire a lease, generate an app snapshot from the installed CLI, launch the installed app bundle against the smoke fixture, assert the `SimulatorBrokerApp` process stays alive, restore any preexisting default install metadata including symlink target contents, and clean up only the simulators provisioned by the smoke run afterward - `npm run package:distribution` builds the app in `Release`, requires operator-supplied `SIMBROKER_DISTRIBUTION_TEAM_ID` plus `SIMBROKER_DISTRIBUTION_SIGNING_IDENTITY`, optionally consumes `SIMBROKER_NOTARYTOOL_PROFILE`, and writes a machine-readable readiness summary under `artifacts/distribution/` diff --git a/spec/project-structure.md b/spec/project-structure.md index c6a3a98..09b000b 100644 --- a/spec/project-structure.md +++ b/spec/project-structure.md @@ -10,6 +10,9 @@ Related: `spec/README.md`, `spec/global-simulator-broker.md`, `references/README protected-path, and handoff contract - `CHANGELOG.md` — published version history for tagged releases - `.github/workflows/` — public Node test CI and tag-driven CLI release +- `.github/ISSUE_TEMPLATE/` — install-failure, bug, and feature issue forms +- `.github/pull_request_template.md` — public-patch PR checklist; no harness + session required - `spec/` — active source of truth, including worker-ready task specs under `spec/tasks/` - `docs/` — public newcomer docs (getting started, concepts, status) and the README screenshot; not source of truth