Skip to content

armgit / SOMA

Public Imported from GitHub
0

Desktop app for designing parametric 3D models in CadQuery together with the coding agent of your choice

Docs: accept pull requests, English for comments and commits

Kai-Jungsthoefelf49c9101acc2
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..2645747
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,15 @@
+## What and why
+
+<!-- What does this change, and why? Link the issue, for example: Fixes #12 -->
+
+## Tests
+
+- [ ] `npm run typecheck` and `npm test` pass
+- [ ] Tested on: <!-- Windows / macOS / Linux -->
+- [ ] Entry under "Unreleased" in CHANGELOG.md, if users notice the change
+
+<!-- For interface changes: add a screenshot -->
+
+## License
+
+- [ ] I agree that my contribution is licensed under the GPL, version 3 or later, with the SOMA Model Exception (see CONTRIBUTING.md)
diff --git a/CLAUDE.md b/CLAUDE.md
index decd4fc..6dc2a32 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -25,7 +25,7 @@ Details in `app/README.md`.
- `src/shared/` `types.ts` (IPC contract), `settings.ts` (defaults, validation, mouse bindings, E81), `editable.ts`, `help.ts`, `skillname.ts`, `version.ts`.
- `resources/` `template/` (template for user projects incl. `AGENTS.md`), `skills/` (bundled skills, among them `soma-app.md` as the user guide for help and agent, E83), `help/` (images of the guide), `icon.*` (generated with `scripts/make-icon.py`).
- `test/` test suites, CDP client, screenshots. `SOMA_TEST_EXE` runs them against a packaged app.
-- `electron-builder.config.cjs` installation packages, `build-resources/` large icon for them. CI for all three systems in `.github/workflows/dist.yml`.
+- `electron-builder.config.cjs` installation packages, `build-resources/` large icon for them. CI for all three systems in `.github/workflows/dist.yml`, checks for pull requests and pushes in `checks.yml`.
**`python/soma/`** helper library and CLI
- API: `add_part` (with `group=`, `role=`), `param` (`params.py`, E74), `import_step`, `import_assembly`, standard parts in `fasteners.py` (dimension tables from bd_warehouse in `data/fasteners/`). Plain CadQuery scripts (E100): compatibility mode for `show_object`, `ocp_vscode` and `result` in `cqcompat.py`.
@@ -42,7 +42,7 @@ Details in `app/README.md`.
**`docs/`** `images/` for the README, `phase0-ergebnisse.md` (finished prototype, code in the Git history up to `v0.5.0`).
-**Root:** `README.md`, `README.zh-CN.md` (AI translation, linked at the top of the README), `CHANGELOG.md`, `LICENSE`, `MODEL-EXCEPTION.md`, `THIRD_PARTY_NOTICES.md` (licenses of bundled components, shipped with the packages), `SECURITY.md`, `CONTRIBUTING.md` (issues only, no pull requests for now). Issue templates in `.github/ISSUE_TEMPLATE/`.
+**Root:** `README.md`, `README.zh-CN.md` (AI translation, linked at the top of the README), `CHANGELOG.md`, `LICENSE`, `MODEL-EXCEPTION.md`, `THIRD_PARTY_NOTICES.md` (licenses of bundled components, shipped with the packages), `SECURITY.md`, `CONTRIBUTING.md` (issues and pull requests). Issue templates in `.github/ISSUE_TEMPLATE/`, pull request template in `.github/pull_request_template.md`.
## Commands
@@ -78,8 +78,8 @@ npm run dist # installation package for this system, run
### Language (E73, E89)
-- **English:** everything users, contributors or the agent see: interface, messages, dialogs, output and errors of `soma`, docstrings of the public API, skills including their header, handover notes to the agent, `AGENTS.md` and `model.py` of the template. Also all public documents in the repo: `README.md`, `CHANGELOG.md`, this `CLAUDE.md`, `THIRD_PARTY_NOTICES.md`, `SECURITY.md`, issue templates, release texts. Numbers with a decimal point.
-- **German:** internal docs (`app/README.md`, `docs/phase0-ergebnisse.md`, the local working documents), code comments, commit messages, test descriptions.
+- **English:** everything users, contributors or the agent see: interface, messages, dialogs, output and errors of `soma`, docstrings of the public API, skills including their header, handover notes to the agent, `AGENTS.md` and `model.py` of the template. Also all public documents in the repo: `README.md`, `CHANGELOG.md`, this `CLAUDE.md`, `THIRD_PARTY_NOTICES.md`, `SECURITY.md`, issue templates, release texts. Numbers with a decimal point. Code comments, commit messages and test descriptions are in English too (since November 2026, older code still has German comments).
+- **German:** internal docs (`app/README.md`, `docs/phase0-ergebnisse.md`, the local working documents).
- What the app recognizes from older projects (commit subjects, trailers) it also recognizes in the old German form.
- `README.md` in the root is the start page on GitHub (E70): plain and short, no emojis, images in `docs/images/`. `README.zh-CN.md` is an AI translation of it, marked as such at the top: when the README changes, update the translation too.
@@ -117,12 +117,12 @@ npm run dist # installation package for this system, run
## Docs and way of working
-- The maintainer speaks German: answer in German. If a decision is really theirs, ask a single question. What I decide without asking goes into `PLAN.md` under "Noch nicht ausdrücklich bestätigt".
+- The maintainer speaks German: answer them in German. Contributors get answers in their own language. If a decision is really theirs, ask a single question. What I decide without asking goes into `PLAN.md` under "Noch nicht ausdrücklich bestätigt".
- After a step, update:
- `PLAN.md`: phase status, open points, risks.
- `app/README.md` when commands or structure change, and the structure here.
- `CHANGELOG.md`: what the user notices, briefly under "Unreleased", in English (E70, E89).
- `README.md` only for big new features.
- `THIRD_PARTY_NOTICES.md` when a bundled component is added, removed or changes its license.
-- Commits only on request, split by topic (e.g. `python/`, `app/`, docs), with a German message.
+- Commits only on request, split by topic (e.g. `python/`, `app/`, docs), with an English message. Pull requests from contributors are squash-merged.
- **Version number (E68):** major.minor.bugfix, one for app and `soma`, in `app/package.json` and `python/soma/__init__.py` (change both the same, `npm run test:unit` checks it). Bump only on request: bugfix for fixes, minor for new features, major for breaks with older models or agent instructions. "Unreleased" in the changelog then becomes the new version with date, plus an annotated tag `vX.Y.Z`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3282280..22813c2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,9 +1,9 @@
# Contributing
-Thanks for your interest in SOMA.
+Thanks for your interest in SOMA. Bug reports, ideas and pull requests are welcome. SOMA is maintained by one person in
+their spare time, so please expect a few days until an answer.
-For now, SOMA is developed by one person, and pull requests are not accepted. The most helpful contributions are
-issues:
+## Issues
- **Bug reports:** what happened, the steps to get there, and the system info from Settings > About > "Copy system info".
- **Ideas:** describe what you were trying to design and what got in the way. A real example helps more than a feature
@@ -13,4 +13,59 @@ issues:
Please use the [issue templates](https://github.com/Kai-Jungsthoefel/SOMA/issues/new/choose). Security problems go
through private reporting, see [SECURITY.md](SECURITY.md).
-You are free to fork SOMA under the terms of the [GPL](LICENSE).
+## Pull requests
+
+- **Small fixes** (bugs, typos, docs): open a pull request directly.
+- **Anything bigger** (a new feature, changes to the `.soma` format, the `soma` API or command line, the agent
+ instructions or the skills): open an issue first and describe what you want to change. This avoids work that cannot be
+ merged.
+- One topic per pull request. Issues labeled
+ [good first issue](https://github.com/Kai-Jungsthoefel/SOMA/labels/good%20first%20issue) are a good place to start.
+
+### Development setup
+
+Structure, commands and code principles are in [CLAUDE.md](CLAUDE.md), the instructions for agents working on SOMA.
+They apply to people as well.
+
+```
+# once: Python environment with soma and CalculiX
+powershell -File python/scripts/setup_env.ps1
+
+# in app/
+npm install
+npm start
+```
+
+Development is set up and tested on Windows. On macOS and Linux it may need adjustments. If you get it running there, a
+pull request that documents the steps is very welcome.
+
+### Before you open a pull request
+
+- `npm run typecheck` and `npm test` pass (in `app/`). If you changed animations, analysis, FEM or the render window,
+ also run `node test/run-all.mjs animation fem` after `npm run build`.
+- Anything users notice gets a short entry under "Unreleased" in [CHANGELOG.md](CHANGELOG.md).
+- For interface changes, add a screenshot to the pull request.
+- Say which system you tested on.
+
+### Language
+
+SOMA is written in English: interface, messages, `soma` output, skills, docs, code comments and commit messages. Older
+code still has comments in German, you don't need to translate them.
+
+References like `(E12)` in the code point to the maintainer's decision log, which is not public. You can ignore them.
+
+### Coding agents
+
+Using a coding agent is fine, most of SOMA was written with Claude Code. [CLAUDE.md](CLAUDE.md) gives your agent the
+context it needs. You are responsible for the change: read it, run the tests, and be able to explain it.
+
+## License of contributions
+
+SOMA is licensed under the GPL, version 3 or any later version, with the [SOMA Model Exception](MODEL-EXCEPTION.md). The
+exception makes sure that what people design with SOMA belongs to them.
+
+By opening a pull request, you agree that your contribution is licensed under the same terms, including the Model
+Exception. Contributions to `python/soma/cqruntime.py` and `python/soma/fasteners.py` are also licensed under the Apache
+License 2.0, like these files.
+
+You are also free to fork SOMA under the terms of the [GPL](LICENSE).
diff --git a/README.md b/README.md
index 77a4d81..5584113 100644
--- a/README.md
+++ b/README.md
@@ -90,7 +90,7 @@ Early prototype. The current version is on the [releases](https://github.com/Kai
## Feedback
-Bug reports, ideas and experiences with different agents are very welcome as [issues](https://github.com/Kai-Jungsthoefel/SOMA/issues/new/choose). Pull requests are not accepted for now, see [CONTRIBUTING.md](CONTRIBUTING.md).
+Bug reports, ideas and experiences with different agents are very welcome as [issues](https://github.com/Kai-Jungsthoefel/SOMA/issues/new/choose). Pull requests are welcome too, see [CONTRIBUTING.md](CONTRIBUTING.md).
## Running from source
diff --git a/README.zh-CN.md b/README.zh-CN.md
index b3c4bb9..9d1de00 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -96,7 +96,7 @@ SOMA 本身不是智能体。任何能读取文件并运行命令的 CLI 智能
## 反馈
-非常欢迎以 [issues](https://github.com/Kai-Jungsthoefel/SOMA/issues/new/choose) 的形式提交错误报告、想法以及使用不同智能体的经验。最好用英文;也可以用中文,维护者会借助翻译工具阅读。目前不接受 Pull Request,见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+非常欢迎以 [issues](https://github.com/Kai-Jungsthoefel/SOMA/issues/new/choose) 的形式提交错误报告、想法以及使用不同智能体的经验。最好用英文;也可以用中文,维护者会借助翻译工具阅读。也欢迎提交 Pull Request,见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 从源码运行