Skip to content

Commit 0144dad

Browse files
protosphinxprotosphinx
committed
Prepare the public contributor launch
1 parent 8db0b80 commit 0144dad

12 files changed

Lines changed: 480 additions & 0 deletions

‎.github/ISSUE_TEMPLATE/bug.yml‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
name: Bug report
2+
description: Report a reproducible PartMode defect with the evidence needed to investigate it.
3+
title: "[Bug] "
4+
labels:
5+
- bug
6+
- triage
7+
body:
8+
- type: dropdown
9+
id: area
10+
attributes:
11+
label: Area
12+
options:
13+
- Sketch and constraints
14+
- Part features and topology
15+
- Assemblies and mates
16+
- Drawings and export
17+
- Agents, MCP, or headless
18+
- Browser UI or accessibility
19+
- Server or accounts
20+
- Build or documentation
21+
validations:
22+
required: true
23+
- type: dropdown
24+
id: mode
25+
attributes:
26+
label: Product mode
27+
options:
28+
- Browser-local CAD
29+
- Browser-approved agent session
30+
- Server-headless agent session
31+
- Server, account, or build tooling
32+
validations:
33+
required: true
34+
- type: input
35+
id: version
36+
attributes:
37+
label: Release SHA or source commit
38+
placeholder: Full commit SHA or the value shown by the running build
39+
validations:
40+
required: true
41+
- type: textarea
42+
id: fixture
43+
attributes:
44+
label: Minimal project, template, or fixture
45+
description: Name a built-in template, attach the smallest project fixture that reproduces the problem, or write "Not applicable" for non-CAD reports.
46+
validations:
47+
required: true
48+
- type: textarea
49+
id: reproduction
50+
attributes:
51+
label: Reproduction steps
52+
placeholder: |
53+
1. Open ...
54+
2. Choose ...
55+
3. Observe ...
56+
validations:
57+
required: true
58+
- type: textarea
59+
id: expected
60+
attributes:
61+
label: Expected result
62+
validations:
63+
required: true
64+
- type: textarea
65+
id: actual
66+
attributes:
67+
label: Actual result and diagnostics
68+
description: Include typed error codes and bounded logs. Do not include credentials, private data, or proprietary project content.
69+
validations:
70+
required: true
71+
- type: textarea
72+
id: exact-evidence
73+
attributes:
74+
label: Exact or runtime evidence
75+
description: Include the document revision or hash, B-rep or topology result, export manifest, or browser settlement evidence that applies.
76+
- type: input
77+
id: environment
78+
attributes:
79+
label: Browser and operating system
80+
placeholder: Chrome 140 on macOS 15, if relevant
81+
- type: textarea
82+
id: commands
83+
attributes:
84+
label: Commands already run
85+
placeholder: npm run ci:gate; npm run smoke:...
86+
- type: dropdown
87+
id: contribute
88+
attributes:
89+
label: Would you like to work on a fix?
90+
options:
91+
- "Yes"
92+
- I can test a fix
93+
- Not at this time
94+
- type: checkboxes
95+
id: confirmations
96+
attributes:
97+
label: Confirmations
98+
options:
99+
- label: I searched existing issues for the same problem.
100+
required: true
101+
- label: Any attached fixture contains no credentials, private data, or standards content without redistribution rights.
102+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Report a security vulnerability privately
4+
url: https://github.com/BOMWiki/partmode/security/advisories/new
5+
about: Do not disclose security-sensitive information in a public issue.

‎.github/ISSUE_TEMPLATE/feature.yml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
name: Contribution proposal
2+
description: Propose a scoped user workflow or technical improvement before implementation.
3+
title: "[Proposal] "
4+
labels:
5+
- proposal
6+
- triage
7+
body:
8+
- type: textarea
9+
id: workflow
10+
attributes:
11+
label: User workflow or problem
12+
description: Describe the concrete workflow and who is blocked today.
13+
validations:
14+
required: true
15+
- type: dropdown
16+
id: actor
17+
attributes:
18+
label: Primary workflow
19+
options:
20+
- Human browser workflow
21+
- Typed agent workflow
22+
- Shared human and agent workflow
23+
- Contributor or maintainer workflow
24+
validations:
25+
required: true
26+
- type: textarea
27+
id: outcome
28+
attributes:
29+
label: Proposed outcome
30+
description: Describe observable behavior, not only an implementation approach.
31+
validations:
32+
required: true
33+
- type: checkboxes
34+
id: boundaries
35+
attributes:
36+
label: Affected boundaries
37+
options:
38+
- label: Browser UI or accessibility
39+
- label: Saved-project schema or compatibility
40+
- label: Exact kernel or persistent topology
41+
- label: Agent protocol, permissions, or preview and commit
42+
- label: Server-headless storage or execution
43+
- label: Import, export, or drawings
44+
- label: Tests, documentation, or build tooling
45+
- type: textarea
46+
id: evidence
47+
attributes:
48+
label: Acceptance evidence
49+
description: Name the document, runtime, kernel, artifact, and browser evidence that would prove completion.
50+
validations:
51+
required: true
52+
- type: textarea
53+
id: compatibility
54+
attributes:
55+
label: Saved-project and protocol compatibility
56+
description: Explain whether old projects, extensions, agent clients, or artifacts are affected.
57+
- type: textarea
58+
id: non-goals
59+
attributes:
60+
label: Scope and non-goals
61+
description: Keep the first contribution reviewable and explicit.
62+
validations:
63+
required: true
64+
- type: dropdown
65+
id: contribute
66+
attributes:
67+
label: Contribution intent
68+
options:
69+
- I want to implement this
70+
- I can provide fixtures or testing
71+
- I am requesting maintainer feedback only
72+
validations:
73+
required: true
74+
- type: checkboxes
75+
id: confirmations
76+
attributes:
77+
label: Confirmations
78+
options:
79+
- label: I searched existing issues and the contribution roadmap.
80+
required: true
81+
- label: I will open a focused change and add the narrowest relevant regression if the boundary is accepted.
82+
required: true

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
## Linked issue
2+
3+
Closes #
4+
5+
## What changed
6+
7+
## Scope and non-goals
8+
9+
## Saved-project and protocol compatibility
10+
11+
## Evidence
12+
13+
| Boundary | Evidence |
14+
| --- | --- |
15+
| Static or document contract | |
16+
| Exact runtime or kernel | |
17+
| Browser-visible behavior | Not applicable, or add evidence |
18+
19+
## Verification
20+
21+
- `npm run ci:gate`: PASS / not run
22+
- `npm run smoke:...`: PASS / not run
23+
24+
## Checklist
25+
26+
- [ ] The change is focused on the linked issue.
27+
- [ ] Behavior changes include the narrowest relevant regression.
28+
- [ ] Affected documentation is updated.
29+
- [ ] No credentials, private deployment material, customer data, or unlicensed standards content is included.
30+
- [ ] Exact CAD completion is not inferred only from screenshots, DOM state, schema declarations, or mesh counts.

‎CHANGELOG.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Public-source changelog
2+
3+
PartMode's public repository begins with a standalone product source snapshot
4+
rather than a reconstruction of private development history. This changelog
5+
records public source milestones from that point forward.
6+
7+
## Unreleased
8+
9+
- No public-source changes recorded yet.
10+
11+
## Public source release: 2026-08-11
12+
13+
- Added the contributor architecture map, candidate roadmap, issue forms, pull
14+
request template, and scoped contribution evidence guidance.
15+
- Added an 18-second verified workflow demo and a 1280 by 640 social preview.
16+
- Published the first tagged GitHub prerelease for the standalone product
17+
source. The tag is a source snapshot, not a stability or certification claim.
18+
19+
## Initial public source snapshot: 2026-08-10
20+
21+
- Published the standalone PartMode product source under AGPL-3.0-only.
22+
- Included browser-local parametric modeling, assemblies, exact B-rep
23+
evaluation, drawings, exchange formats, browser-approved agents, and optional
24+
server-headless projects.
25+
- Included focused CI, a scheduled CAD regression workflow, contributor
26+
guidance, architecture documentation, and a contribution roadmap.
27+
28+
This snapshot is not an API-stability promise, a certified manufacturing
29+
release, or a prebuilt binary distribution. GitHub's source archives are the
30+
release artifact unless a future release explicitly lists and verifies another
31+
artifact.

‎README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,14 @@ standard interchange formats.
1616

1717
[Try PartMode](https://partmode.com/) · [Read the in-product help](https://partmode.com/help)
1818

19+
[![PartMode contributor demo: open a template, edit a parameter, approve a typed agent change, rebuild exact geometry, and export STEP](docs/media/partmode-contributor-demo.gif)](docs/media/partmode-contributor-demo.mp4)
20+
21+
_18-second contributor demo: open an editable template, make a human parameter
22+
edit, approve a typed agent change, rebuild exact geometry, and export STEP._
23+
24+
The demo was captured locally from the public source snapshot at `8db0b804`
25+
using the production typed-agent protocol. See the [capture evidence](docs/media/README.md).
26+
1927
## What is included
2028

2129
- Parametric sketches and feature history
@@ -30,6 +38,22 @@ PartMode is engineering software, not a certification authority. Validate
3038
dimensions, tolerances, material choices, and released manufacturing data for
3139
your application.
3240

41+
## Architecture at a glance
42+
43+
```mermaid
44+
flowchart LR
45+
H["Human browser UI"] --> D["Canonical schema-5 document"]
46+
M["Typed agent client"] --> C["Permissioned preview and commit"]
47+
C --> D
48+
D --> K["OpenCascade WASM exact kernel"]
49+
K --> E["B-rep evidence and exports"]
50+
```
51+
52+
The browser and agent paths edit the same document model and reuse the same
53+
exact kernel-worker implementation. See the
54+
[architecture guide](docs/architecture.md) for the server, relay, headless,
55+
drawing, and verification entry points.
56+
3357
## Run locally
3458

3559
PartMode requires Node.js 22.13 or newer.
@@ -54,6 +78,37 @@ runtime manifests, and exercises the local HTTP, account, identity, MCP, cloud,
5478
and entrypoint contracts. The larger CAD and browser suites remain available as
5579
individual `smoke:*` scripts and through `npm run release:gate`.
5680

81+
## Contribute
82+
83+
Start with a [good first issue](https://github.com/BOMWiki/partmode/labels/good%20first%20issue)
84+
or a [help wanted issue](https://github.com/BOMWiki/partmode/labels/help%20wanted).
85+
Comment before starting so scope and ownership are clear.
86+
87+
For a behavior change:
88+
89+
1. Stay within the issue's accepted boundary.
90+
2. Add or update the narrowest relevant regression.
91+
3. Run `npm run ci:gate`.
92+
4. Run every affected `smoke:*` command listed in the issue.
93+
94+
`ci:gate` is the focused baseline. CAD, kernel, assembly, export, and visible UI
95+
changes also need their affected smoke checks. For CAD changes, screenshots and
96+
mesh counts are supporting evidence only. Report the settled document result
97+
and exact kernel, B-rep, topology, or export evidence required by the issue.
98+
Visible behavior changes also need browser evidence.
99+
100+
| Area | Start here | Typical focused checks |
101+
| --- | --- | --- |
102+
| Browser UI and recovery | `src/page.html`, `src/static/studio.js`, `src/static/studio-storage.js` | `smoke:browser`, `smoke:usability-ui` |
103+
| Documents and features | `src/static/studio-project-v5.js`, `src/static/studio-v5-runtime-document.js` | affected `smoke:*` feature test |
104+
| Exact geometry and topology | `src/static/studio-kernel.worker.js`, `src/static/studio-brep-evidence.js`, `src/static/studio-topo-naming.js` | `smoke:brep-evidence`, `smoke:topology-hash`, `smoke:cad-regression` |
105+
| Assemblies | `src/static/studio-v5-assembly.js`, `src/static/studio-assembly-*` | `smoke:assembly-runtime` plus the affected assembly smoke |
106+
| Typed agents and headless | `src/static/studio-agent-service.js`, `src/mcp.ts`, `src/relay-hub.ts`, `src/headless-sessions.ts` | `smoke:cloud`, `smoke:mcp`, `smoke:headless-mcp` |
107+
| Drawings and exchange | `src/static/studio-drawing-*`, kernel import and export handlers | affected `smoke:drawing-*`, `smoke:step-determinism` |
108+
109+
[Contributing guide](CONTRIBUTING.md) · [Architecture](docs/architecture.md) ·
110+
[Contribution roadmap](ROADMAP.md) · [Public-source changelog](CHANGELOG.md)
111+
57112
## Repository scope
58113

59114
This repository contains the standalone PartMode product source, public

‎ROADMAP.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# PartMode contribution roadmap
2+
3+
This roadmap lists candidate contribution areas. It does not assign delivery
4+
dates, promise compatibility milestones, or imply that every item will ship.
5+
Propose substantial changes in an issue before implementation so the boundary
6+
and evidence can be agreed first.
7+
8+
## Browser and headless portability
9+
10+
- Import canonical project bundles and templates into server-headless projects.
11+
- Add configuration-table authoring to the typed headless path.
12+
- Expand headless artifact support beyond STEP when exact evidence permits it.
13+
- Let an account owner delete one durable headless project without deleting the
14+
complete account.
15+
16+
The browser and headless paths intentionally have different authority, storage,
17+
visibility, and artifact boundaries today. Portability work must preserve those
18+
differences rather than silently widening access.
19+
20+
## Assembly edit context
21+
22+
- Support complete nested occurrence paths when editing a part in assembly
23+
context.
24+
- Add safely bounded associative cross-part references to ghosted geometry.
25+
26+
The current workflow supports direct part occurrences. Missing or ambiguous
27+
paths must continue to fail closed.
28+
29+
## Modeling parity
30+
31+
- Let first-class constrained sketches drive Revolve.
32+
- Extend exact tangent-chain propagation beyond constant-radius Fillet chains.
33+
- Improve contributor fixtures for safe parameter mutation, topology naming,
34+
and fresh-worker rebuilds.
35+
36+
New modeling behavior must carry canonical document intent and exact kernel
37+
evidence. Proximity and traversal order are not acceptable reference fallbacks.
38+
39+
## Drawing parity
40+
41+
- Allow more topology-bound annotations on derived views.
42+
- Broaden controlled GD&T and PMI coverage without implying standards
43+
certification.
44+
- Extend exact exchange coverage while keeping approximation policies explicit.
45+
46+
## Scale and maintainability
47+
48+
- Establish measurable interaction and rebuild budgets for large assemblies and
49+
software-rendered browsers.
50+
- Improve shared headless-worker throughput without weakening tenant isolation.
51+
- Extract cohesive coordinators from `src/static/studio.js` while preserving
52+
schema, runtime, and browser behavior.
53+
54+
## Explicit boundaries
55+
56+
PartMode does not currently promise:
57+
58+
- CAM or native DWG authoring;
59+
- engineering simulation, certified analysis, or automated design approval;
60+
- a general standards-certified GD&T or PMI workbench;
61+
- reconstruction of vendor-native feature history, mates, or PMI from STEP;
62+
- identical interactive quality for every assembly size and renderer.
63+
64+
See [limits, evidence, and safety](docs/help/limits-and-safety.md) for the
65+
current product boundary and [CONTRIBUTING.md](CONTRIBUTING.md) for the evidence
66+
required in a change.

0 commit comments

Comments
 (0)