Skip to content

Commit ab1d25e

Browse files
VladimirBrejchaVladimirBrejcha
authored
Merge pull request #10 from fiveonecode/docs/github-community-hygiene
Add issue forms, a light PR template, and an Alpha banner
2 parents c2727e3 + 170244b commit ab1d25e

14 files changed

Lines changed: 321 additions & 2 deletions

‎.agents/manifests/specs.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
id: specs
22
globs:
3+
- .github/ISSUE_TEMPLATE/**
4+
- .github/pull_request_template.md
35
- .github/workflows/**
46
- .gitignore
57
- CHANGELOG.md
@@ -27,6 +29,8 @@ primary_specs:
2729
verification_profile: spec-only
2830
commit_required: true
2931
allowed_paths:
32+
- .github/ISSUE_TEMPLATE/**
33+
- .github/pull_request_template.md
3034
- .github/workflows/**
3135
- .gitignore
3236
- CHANGELOG.md

‎.github/ISSUE_TEMPLATE/bug.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: Bug
2+
description: Something already documented does not behave as specified.
3+
title: "[Bug]: "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Simulator Broker is **Alpha**, **macOS-only**, and needs **Xcode** to
10+
create or run iOS Simulators. Interfaces can change.
11+
12+
Use the install-failure form if `simbroker` never became usable.
13+
Do not paste credentials, private home paths, customer data, or
14+
live lease files.
15+
- type: textarea
16+
id: what-happened
17+
attributes:
18+
label: What happened?
19+
description: Which command, app pane, or script misbehaved?
20+
validations:
21+
required: true
22+
- type: textarea
23+
id: expected
24+
attributes:
25+
label: What should have happened?
26+
validations:
27+
required: true
28+
- type: textarea
29+
id: reproduce
30+
attributes:
31+
label: Steps to reproduce
32+
placeholder: |
33+
1. Run `simbroker …`
34+
2. …
35+
3. See the error
36+
validations:
37+
required: true
38+
- type: input
39+
id: version
40+
attributes:
41+
label: Version or commit
42+
description: Tagged Alpha such as 0.1.0-alpha.1, or a short commit SHA.
43+
placeholder: 0.1.0-alpha.1
44+
validations:
45+
required: true
46+
- type: textarea
47+
id: environment
48+
attributes:
49+
label: Environment
50+
description: macOS, Xcode, and Node.js versions. No private paths.
51+
value: |
52+
- macOS:
53+
- Xcode:
54+
- Node.js:
55+
validations:
56+
required: true
57+
- type: textarea
58+
id: logs
59+
attributes:
60+
label: Redacted logs
61+
render: shell
62+
validations:
63+
required: false
64+
- type: checkboxes
65+
id: confirm
66+
attributes:
67+
label: Before submitting
68+
options:
69+
- label: I understand this is Alpha, macOS-only, and requires Xcode.
70+
required: true
71+
- label: I searched existing issues and did not find a duplicate.
72+
required: true
73+
- label: I removed credentials, private paths, and customer data from this report.
74+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Security advisory
4+
url: https://github.com/fiveonecode/simulator-broker/security/advisories/new
5+
about: Report a vulnerability privately. Do not open a public issue.
6+
- name: Getting started
7+
url: https://github.com/fiveonecode/simulator-broker/blob/main/docs/getting-started.md
8+
about: Install and first-run help. This project is Alpha, macOS-only, and needs Xcode.

‎.github/ISSUE_TEMPLATE/feature.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Feature
2+
description: Propose a change that is not already in the Alpha contract.
3+
title: "[Feature]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Simulator Broker is **Alpha**, **macOS-only**, and needs **Xcode**.
10+
It is maintenance-only infrastructure. There is no Homebrew formula,
11+
notarized app, or npm package yet.
12+
13+
Maintainers may decline requests that add a feature, commercialization,
14+
or UX roadmap.
15+
- type: textarea
16+
id: problem
17+
attributes:
18+
label: What problem are you hitting?
19+
description: Describe the gap a stranger hits today. Not a solution yet.
20+
validations:
21+
required: true
22+
- type: textarea
23+
id: proposal
24+
attributes:
25+
label: What should change?
26+
description: A concrete, bounded change. Link docs or specs if you have them.
27+
validations:
28+
required: true
29+
- type: dropdown
30+
id: surface
31+
attributes:
32+
label: Which surface is this about?
33+
options:
34+
- CLI / broker-core
35+
- Local brokerd service
36+
- macOS operator app
37+
- Install or packaging
38+
- Docs or contributor track
39+
- Other
40+
validations:
41+
required: true
42+
- type: checkboxes
43+
id: confirm
44+
attributes:
45+
label: Before submitting
46+
options:
47+
- label: I understand this is Alpha, macOS-only, and requires Xcode.
48+
required: true
49+
- label: I searched existing issues and did not find a duplicate.
50+
required: true
51+
- label: This is not a security report. I will use a private advisory for vulnerabilities.
52+
required: true

‎.github/ISSUE_TEMPLATE/install-failure.yml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
name: Install failure
2+
description: The CLI, tarball, or local installer did not work on this Mac.
3+
title: "[Install]: "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Simulator Broker is **Alpha**, **macOS-only**, and needs **Xcode** to
10+
create or run iOS Simulators. There is no Homebrew formula, notarized
11+
app, or npm package yet.
12+
13+
Do not paste credentials, private home paths, customer data, or
14+
live lease files. Redact logs first. Security reports go through
15+
[GitHub Security Advisories](https://github.com/fiveonecode/simulator-broker/security/advisories/new),
16+
not a public issue.
17+
- type: dropdown
18+
id: install-path
19+
attributes:
20+
label: What install path did you use?
21+
options:
22+
- CLI-only (`bash scripts/install_local.sh --cli-only`)
23+
- Contributor app + CLI (`npm run install:local`)
24+
- Alpha CLI tarball from GitHub Releases
25+
- Other (describe below)
26+
validations:
27+
required: true
28+
- type: textarea
29+
id: command
30+
attributes:
31+
label: Command that failed
32+
description: Paste the exact command. Do not include private paths.
33+
render: shell
34+
validations:
35+
required: true
36+
- type: textarea
37+
id: expected-actual
38+
attributes:
39+
label: Expected versus actual
40+
description: What should have happened, and what happened instead?
41+
validations:
42+
required: true
43+
- type: input
44+
id: macos
45+
attributes:
46+
label: macOS version
47+
placeholder: "15.6"
48+
validations:
49+
required: true
50+
- type: input
51+
id: xcode
52+
attributes:
53+
label: Xcode version
54+
placeholder: "16.4"
55+
validations:
56+
required: true
57+
- type: input
58+
id: node
59+
attributes:
60+
label: Node.js version
61+
placeholder: "20.19.0"
62+
validations:
63+
required: true
64+
- type: textarea
65+
id: logs
66+
attributes:
67+
label: Redacted logs
68+
description: Paste only the relevant output. Strip home directories and secrets.
69+
render: shell
70+
validations:
71+
required: false
72+
- type: checkboxes
73+
id: confirm
74+
attributes:
75+
label: Before submitting
76+
options:
77+
- label: I understand this is Alpha, macOS-only, and requires Xcode.
78+
required: true
79+
- label: I searched existing issues and did not find a duplicate.
80+
required: true
81+
- label: I removed credentials, private paths, and customer data from this report.
82+
required: true

‎.github/pull_request_template.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
## What changed
2+
3+
<!-- A few sentences. Keep the diff focused on one change. -->
4+
5+
## How you verified
6+
7+
A public patch uses Node.js 20 and the Node suites that match the change.
8+
You do not need the agent harness or a task session directory.
9+
10+
- [ ] `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
11+
- [ ] I did not commit private paths, credentials, generated Xcode projects, local broker state, or task-session artifacts
12+
13+
## Notes
14+
15+
This project is **Alpha**, **macOS-only**, and needs **Xcode** to talk to iOS
16+
Simulators. See [CONTRIBUTING.md](CONTRIBUTING.md).

‎CONTRIBUTING.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33
Thanks for taking the time to improve Simulator Broker.
44

5+
This project is **Alpha**, **macOS-only**, and needs **Xcode** to create or run
6+
iOS Simulators. Report install failures, bugs, and feature requests with the
7+
[issue forms](https://github.com/fiveonecode/simulator-broker/issues/new/choose).
8+
Look at issues labeled `good first issue` if you want a bounded starter task.
9+
510
This page has two tracks:
611

712
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.
3843

3944
### Pull requests
4045

46+
The pull-request template is a short public-patch checklist. It does not ask
47+
for a harness session directory.
48+
4149
- Keep changes focused and reviewable.
4250
- Include tests or explain why a deterministic test is not available.
4351
- Keep private or local context out of committed files.

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,10 @@
33
A local control plane so humans, AI agents, and CI jobs can share iOS Simulators
44
on one Mac without stealing devices from each other.
55

6-
**Status:** Alpha · macOS only · Xcode required
6+
> **Alpha.** macOS only. Xcode is required to create or run iOS Simulators.
7+
> Interfaces can change. There is no Homebrew formula, notarized app, or npm
8+
> package yet.
9+
710
[![Node tests](https://github.com/fiveonecode/simulator-broker/actions/workflows/ci.yml/badge.svg)](https://github.com/fiveonecode/simulator-broker/actions/workflows/ci.yml)
811

912
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.
97100
- [Getting started](docs/getting-started.md) — install, first-run, reinstall, and uninstall
98101
- [Concepts](docs/concepts.md) — host, project, purpose, lease, pin, and `brokerd`
99102
- [Current capabilities](docs/status.md) — what this Alpha already implements
103+
- [Open an issue](https://github.com/fiveonecode/simulator-broker/issues/new/choose) — install failure, bug, or feature
100104
- [Harness integration](spec/harness-integration.md) — make a consumer repo broker-aware
101105
- [Sample consumer repo](examples/harness-adoption/sample-consumer-repo/README.md)
102106

‎docs/getting-started.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ human-readable text by default; pass `--json` for machine-readable payloads.
88
A small public patch follows the public-patches track in
99
[CONTRIBUTING.md](../CONTRIBUTING.md); it does not require the agent harness.
1010

11+
> **Alpha.** macOS only. Xcode is required to create or run iOS Simulators.
12+
> Interfaces can change. There is no Homebrew formula, notarized app, or npm
13+
> package yet.
14+
1115
## Prerequisites
1216

1317
- macOS with Xcode and iOS Simulator support installed
@@ -144,6 +148,12 @@ npm run package:distribution
144148
GitHub Releases attach the Alpha CLI tarball. A signed, notarized app is not
145149
published there yet.
146150

151+
## Report a problem
152+
153+
Use the GitHub issue forms. Pick **Install failure**, **Bug**, or **Feature**.
154+
Do not paste credentials, private home paths, or live lease files. Security
155+
reports go through [SECURITY.md](../SECURITY.md), not a public issue.
156+
147157
## What to read next
148158

149159
- [Concepts](concepts.md)

‎docs/status.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ This Alpha already includes:
2727
- tagged Alpha CLI tarball through `npm run package:cli` and GitHub Releases
2828
- public Node test CI on GitHub-hosted Ubuntu for broker-core, client,
2929
harness-adoption, and public-surface checks
30+
- GitHub issue forms for install failure, bug, and feature, plus a light PR
31+
template that does not require a harness session
3032
- local-debug packaging through `npm run package:local`
3133
- signed distribution packaging through `npm run package:distribution`
3234
- `simbroker project init` for `.simulator-broker/project.json`
@@ -63,4 +65,3 @@ node client/bin/simbroker.mjs simulators boot --alias ui-1
6365
## Lower-priority public follow-through
6466

6567
- Homebrew formula, notarized app, and npm package
66-
- issue templates and starter issues

0 commit comments

Comments
 (0)