World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
Contributing guide, in both languages (#153)
WaylandYang05f8f5e67654
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 00000000..6d466523--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,112 @@+# Contributing to Utopia++[中文](CONTRIBUTING.zh-CN.md)++Welcome. This file covers what is specific to this repository; general open-source etiquette is assumed.++## Branches and how changes land++| Branch | What it is |+|---|---|+| `main` | Stable, matches the released version. Only maintainers merge into it, from `dev` |+| `dev` | Integration branch. Every contribution lands here first |++Your path as a contributor:++```bash+git switch dev && git pull+git switch -c fix/some-thing # branch off dev, not main+# make changes, commit with -s (see DCO below)+git push -u origin fix/some-thing+```++Then open a PR with **base `dev`, not `main`**. A maintainer merges once CI and review pass.++Merging `dev → main` is done by maintainers on their own schedule; contributors don't need to think about it.++Both branches are protected: pull request required, CI (`backend` and `web`) must pass, no force pushes, no deletions, and admins are held to the same rules.++## Issue first, or straight to a PR++| Change | What to do |+|---|---|+| Bug fixes, docs, i18n strings, tests | Open a PR directly |+| New features, dependency changes | Open an [issue](https://github.com/deeplethe/utopia/issues) first and describe the use case |+| Data model, ontology contract, public API | Discuss in an issue, then land an [ADR](docs/decisions/) before writing code |++`docs/decisions/` is where this project's reasoning lives. An ADR records **why this and not that**, including the approaches that were tried and failed. For a change of any size, that document outlives the code.++## Local setup++Requires Docker, Rust 1.85+, Node 20+, pnpm.++```bash+docker compose up -d db # Postgres with pgvector+cargo run -p utopia-server # runs migrations, :1516+cd web && pnpm install && pnpm dev # :5173, proxies /api to the backend+```++## Before you push++CI runs exactly this. Green locally means green in CI:++```bash+cargo fmt --all --check+cargo clippy --workspace --all-targets -- -D warnings+cargo test --workspace+cd web && pnpm install --frozen-lockfile && pnpm build # build type-checks+```++### Database-backed tests **skip** without the env var++This is the easiest thing to get wrong here. A green `cargo test --workspace` does not mean everything ran. A number of tests begin like this:++```rust+let Ok(url) = std::env::var("UTOPIA_DATABASE_URL") else {+ eprintln!("skipping: UTOPIA_DATABASE_URL not set");+ return Ok(());+};+```++They guard what the compiler cannot see: table aliases inside SQL strings, how `NULL` behaves in a comparison, rows an `INNER JOIN` silently drops, whether a recursive CTE expands the same ancestor twice under diamond inheritance. `cargo check` and clippy say nothing about any of it.++If you touched SQL under `crates/utopia-store/`, set it and run again:++```bash+export UTOPIA_DATABASE_URL=postgres://utopia:utopia@localhost:5432/utopia+cargo test --workspace+```++## Things review will send back++**Don't collide migration numbers.** `migrations/` rolls forward by number. Check the latest number on `main` before opening a PR — two branches each writing an `0011_` has happened, and after the merge neither one runs.++**UI strings go in i18n.** Add to both `web/src/i18n/en.ts` and `zh.ts`; no hard-coded strings in components.++**Comments explain why.** This repository comments densely and deliberately records the traps it fell into ("the first version used OR, and the Elon Musk article then produced a snapshot every 6KB"). Follow that. A comment restating what the code does will be asked to go.++**Commit messages: one English sentence, stating the motivation.** No long body. Skim `git log` for the register.++## DCO: sign off every commit++We use the [DCO](https://developercertificate.org/), not a CLA. You keep the copyright on your code; you are certifying that you have the right to submit it under Apache-2.0.++Commit with `-s` and git adds the line for you:++```bash+git commit -s -m "Fix the thing"+```++which appends:++```+Signed-off-by: Your Name <your@email>+```++Forgot? `git commit --amend -s` for the last commit, or `git rebase --signoff HEAD~3` for several (adjust the count), then `git push -f`.++Use a real name and a reachable email address.++## License++By contributing you agree that your work is released under [Apache-2.0](LICENSE).diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.mdnew file mode 100644index 00000000..231418b5--- /dev/null+++ b/CONTRIBUTING.zh-CN.md@@ -0,0 +1,112 @@+# 参与 Utopia++[English](CONTRIBUTING.md)++欢迎。这份文件只写这个仓库特有的规矩 —— 通用的开源礼仪就不重复了。++## 分支与合并流程++| 分支 | 是什么 |+|---|---|+| `main` | 稳定分支,对应已发布的版本。只由仓库管理者从 `dev` 合入 |+| `dev` | 集成分支,所有贡献先到这里 |++贡献者的路径:++```bash+git switch dev && git pull+git switch -c fix/some-thing # 从 dev 开新分支,不要从 main+# 改代码,提交时带 -s(见下面 DCO)+git push -u origin fix/some-thing+```++然后开 PR,**base 选 `dev`,不是 `main`**。CI 通过、review 通过之后由维护者合并。++`dev → main` 的合并由仓库管理者择期发起,贡献者不需要管。++两个分支都开了保护:必须走 PR,CI(`backend` 与 `web`)必须通过,禁止强推与删除,管理员同样受约束。++## 先开 issue 还是直接提 PR++| 改动 | 怎么做 |+|---|---|+| Bug 修复、文档、i18n 文案、测试 | 直接提 PR |+| 新功能、依赖变更 | 先开 [issue](https://github.com/deeplethe/utopia/issues) 说清场景 |+| 动数据模型、本体契约、公开 API | 先开 issue 讨论,落一篇 [ADR](docs/decisions/) 再动手 |++`docs/decisions/` 是这个项目主要的决策载体。里面记的不是「改了什么」,是**「为什么这样而不是那样」**,以及当时试过、失败了的做法。改动够大时,那篇文档比代码本身更值钱。++## 起本地环境++依赖:Docker、Rust 1.85+、Node 20+、pnpm。++```bash+docker compose up -d db # pgvector 版 Postgres+cargo run -p utopia-server # 自动跑迁移,:1516+cd web && pnpm install && pnpm dev # :5173,/api 代理到后端+```++## 提交前跑什么++CI 就是下面这几条,本地过了 CI 基本不会红:++```bash+cargo fmt --all --check+cargo clippy --workspace --all-targets -- -D warnings+cargo test --workspace+cd web && pnpm install --frozen-lockfile && pnpm build # build 含类型检查+```++### 带库的测试没设环境变量会**跳过**,不是失败++这是这个仓库最容易误判的一点。`cargo test --workspace` 全绿不等于全跑了 —— 一批测试开头长这样:++```rust+let Ok(url) = std::env::var("UTOPIA_DATABASE_URL") else {+ eprintln!("跳过:未设 UTOPIA_DATABASE_URL");+ return Ok(());+};+```++它们守的是**编译器看不见的东西**:SQL 里的表别名、`NULL` 参与比较时的行为、`INNER JOIN` 悄悄滤掉的行、递归 CTE 在菱形继承下会不会把同一个祖先展开两次。`cargo check` 和 clippy 对这些一个字都不说。++碰了 `crates/utopia-store/` 里的 SQL,请把它设上再跑一遍:++```bash+export UTOPIA_DATABASE_URL=postgres://utopia:utopia@localhost:5432/utopia+cargo test --workspace+```++## 几条会被 review 拦下来的++**迁移编号别撞。** `migrations/` 按序号前滚。开 PR 前看一眼 `main` 上最新的号 —— 两个分支各写一个 `0011_` 已经发生过一次,合并之后谁都跑不起来。++**UI 文案进 i18n。** `web/src/i18n/en.ts` 与 `zh.ts` 两边都要加,不要在组件里硬编码字符串。++**代码注释写「为什么」。** 这个仓库的注释密度偏高,而且刻意记录踩过的坑(「第一版写的是『或』,结果 Elon Musk 那篇每 6KB 就取一张」)。跟着这个风格走 —— 复述代码在做什么的注释会被要求删掉。++**提交信息一句英文,说清动机。** 不写长 body。看一眼 `git log` 就知道调子。++## DCO:每个提交要签++我们用 [DCO](https://developercertificate.org/)(开发者原创声明),不用 CLA。你保留自己代码的著作权,只是声明你有权按 Apache-2.0 提交它。++用 `-s` 提交即可,git 会自动加上署名行:++```bash+git commit -s -m "Fix the thing"+```++提交末尾会多出:++```+Signed-off-by: 你的名字 <你的邮箱>+```++忘了签的话,最后一个提交用 `git commit --amend -s`,多个提交用 `git rebase --signoff HEAD~3`(数字换成实际条数),然后 `git push -f`。++署名用的名字和邮箱要是真实可联系的。++## 许可++提交即表示你的贡献按 [Apache-2.0](LICENSE) 发布。