Thank you for your interest in contributing! Octop is the control-plane application in the Octop Harness ecosystem.
Prerequisites: Python 3.12+, Node.js 18+, uv
git clone https://github.com/TencentCloud/Octop.git octop
cd octop
make install # backend dev dependencies
make install-hooks # once per clone: pre-commit runs make all + dashboard build
make all # format-all + backend lint + typecheck + test (ship bar)For frontend work (separate terminal):
make dev-frontend # Vite dev server
make lint-frontend
make typecheck-frontend
make check-all # full stack quality gate| Command | Description |
|---|---|
make install |
Install Python dev dependencies |
make install-hooks |
Point git at .githooks (pre-commit: make all + dashboard build) |
make all |
format-all + backend lint + typecheck + test |
make check-all |
Full stack quality gate |
make dev |
Start frontend + backend dev servers |
make build |
Build dashboard + Python wheel |
| Branch | Role |
|---|---|
main |
Production source of truth; GitHub default branch; only release / hotfix merges |
develop |
Daily integration; open feature PRs against develop |
release/x.y.z |
Temporary release snapshot; deleted after the version ships |
hotfix/* |
Emergency fix from main; merge to main and back to develop |
feature/* ──PR──► develop ──► release/x.y.z ──PR──► main ──tag v*──► publish
hotfix/* ──PR──► main (+ tag) and ──PR──► develop
Rules:
- Never push
developdirectly tomain— ship only viarelease/x.y.z→main(or hotfix →main). Do not opendevelop→mainbulk merges; they fork history and break post-release sync. - Merge
release/x.y.z→mainwith a merge commit (not squash). Squash drops shared ancestry withdevelop. - Production
v*tags are created onmainafter the release PR merges — not on the release branch before merge. - After a release,
mainmust stay an ancestor ofdevelop. GitHub Actions runssync-main-to-develop.yml(merge first; on conflict, achore/sync-develop-after-*PR). Do not open legacyhead=main→developPRs.
- Fork (if needed) and create a feature branch from
develop - Open the PR with base
develop(notmain, unless it is a release or hotfix) - Add or update tests for behavior changes — CI runs on Linux and Windows; follow the cross-platform rules in AGENTS.md §7 (prefer
tmp_path/pathlib,fake_bin_pathfor mocked binaries,posix_onlyfor Unix-only cases) - Ensure
make install-hooksis enabled locally; runmake all(backend) ormake check-all(full stack) before submitting — pre-commit enforces the same gate - Update
CHANGELOG.mdwhen user-facing behavior changes - Open a PR with a clear description and test plan
See AGENTS.md for module boundaries and coding conventions.
To ensure code quality and collaboration efficiency, please observe the following principles when opening a Pull Request.
Always attach screenshots, whether in the PR description or a comment.
- Let reviewers see the "human" — prove the code was manually reviewed and crafted with care.
- UI changes must include interface screenshots.
- Bug fixes are best shown with before/after comparison images.
- Complex interaction flows may use a GIF / video demo.
💡 Screenshots are not only proof that "it was tested" but also a communication tool that helps reviewers quickly understand intent.
Every PR must include test cases, and they must be complete.
- ✅ New feature → add the corresponding unit / integration tests.
- ✅ Bug fix → add a regression test to prevent recurrence.
- ✅ Adequate coverage → core logic is well covered.
- ✅ All CI workflows must pass → don't expect reviewers to fix failing CI for you.
⚠️ Runnpm test/pytest/go testlocally before pushing to remote.
When using AI-assisted coding, make sure both sides understand the same thing.
- After describing requirements clearly, ask the AI to repeat them to confirm understanding.
- For complex logic, ask the AI to explain its implementation plan.
- After code is generated, proactively ask:
- "Does this implementation satisfy all requirement points?"
- "Are there any missed scenarios?"
- "Is there a simpler implementation?"
🤖 AI is not a one-shot tool; multiple rounds of dialogue are needed to calibrate understanding. Spend 2 minutes confirming rather than 2 hours redoing.
Hold to the minimal-change principle.
- One PR solves only one problem.
- Don't do unrelated refactors (open a separate PR).
- Clear structure, accurate naming, concise logic.
Three questions to ask after AI generates code:
- Is there still room to optimize this code? (performance, readability, edge cases)
- Are all errors / exceptions handled properly?
- Is there redundant code or unused variables / imports?
📝 Good code isn't written once; it's asked into being.
## PR Checklist
- [ ] 📸 UI screenshots / feature demo provided
- [ ] 🧪 Test cases added and passing
- [ ] ✅ All CI workflows passing
- [ ] 🤖 Requirements aligned with AI
- [ ] 🎯 Follows minimal-change principle, clear structure
- [ ] 📝 Optimization suggestions asked and addressed| Rule | Problem solved |
|---|---|
| Attach screenshots | Avoid repeated "was it tested?" questions; build trust |
| Tests + CI | Prevent regression, reduce review burden |
| AI alignment | Reduce "this isn't what I wanted" rework |
| Minimal change + questions | Maintain code maintainability, reject filler code |
Remember: a PR is communication, not a handoff. Make reviewers' lives easy, and your own PR merges faster.
- Cut
release/x.y.zfrom latestdevelop(version bump + CHANGELOG on that branch) - Open PR:
release/x.y.z→mainand merge when green - Tag
v<version>on main tip and push — GitHub Actions builds, publishes to PyPI, and creates the GitHub Release - Delete
release/x.y.z; Actions syncsmain→develop(or openschore/sync-develop-after-*if merge conflicts / branch protection)
Agent-assisted publish: .cursor/skills/publish (/publish <version>).
Branch from main → PR into main (tag if shipping a patch) → PR into develop.
感谢你对 Octop 的关注!Octop 是 Octop Harness 生态中的可自托管 AI 助手平台,支持多用户与多 Agent。
前置条件: Python 3.12+、Node.js 18+、uv
git clone https://github.com/TencentCloud/Octop.git octop
cd octop
make install
make install-hooks # 每个 clone 执行一次:提交前跑 make all + 前端 build
make all # format-all + 后端 lint / typecheck / test前端开发(另开终端):
make dev-frontend
make check-all # 全栈质量门禁| 分支 | 角色 |
|---|---|
main |
生产真源;GitHub 默认分支;仅合入 release / hotfix |
develop |
日常集成;特性 PR 请打向 develop |
release/x.y.z |
临时发版分支;发版完成后删除 |
hotfix/* |
从 main 紧急修复;合入 main 后再合回 develop |
规则:
- 禁止
develop直推/直 merge 到main— 发版必须走release/x.y.z→main(或 hotfix →main)。不要开develop→main大包 PR,否则历史分叉、发版后 sync 必冲突。 release/x.y.z→main请用 merge commit 合并,不要 squash。- 生产
v*tag 仅在 release PR 合入main之后打在 main tip 上。 - 发版后
main必须是develop的祖先;由 Actionssync-main-to-develop.yml自动 sync(冲突或分支保护时会开chore/sync-develop-after-*PR)。不要再用head=main→develop的老 sync PR。
- 从
develop创建特性分支 - PR 的 base 选
develop(release / hotfix 除外) - 补充测试(CI 同时跑 Linux / Windows,路径与假二进制遵循 AGENTS.md §7)
- 本地执行过
make install-hooks;提交前make all或make check-all必须绿(hooks 会强制执行) - 用户可见变更时更新
CHANGELOG.md - 提交 Pull Request
模块边界与编码规范见 AGENTS.md。
为了保证代码质量和协作效率,提交 Pull Request 时请务必遵守以下原则:
必须贴截图,无论放在 PR 描述中还是评论里。
- 让 reviewer 看到"人" —— 证明这段代码是经过人工检查、用心完成的
- UI 变更必须有界面截图
- 功能修复最好有修复前后的对比图
- 复杂的交互流程可用 GIF/视频演示
💡 截图不仅是为了证明"测过了",更是沟通工具,帮助 reviewer 快速理解改动意图。
所有 PR 必须包含测试用例,且测试用例必须完整。
要求:
- ✅ 新增功能 → 新增对应的单元测试/集成测试
- ✅ Bug 修复 → 添加回归测试,防止问题再次发生
- ✅ 覆盖率达标 → 核心逻辑测试覆盖充分
- ✅ 所有 CI Workflow 必须通过 → 不要期望 reviewer 去帮你 fix 失败的 CI
⚠️ 提交前先在本地运行npm test/pytest/go test等,确认无误后再推送到远程。
使用 AI 辅助编码时,务必确认双方理解一致。
做法:
- 明确需求描述后,让 AI 重复一遍需求,确认理解无误
- 对于复杂逻辑,让 AI 解释其实现方案
- 生成代码后,主动追问:
- "这个实现是否满足所有需求点?"
- "是否有遗漏的场景?"
- "有没有更简洁的实现方式?"
🤖 AI 不是一次性工具,需要多轮对话来校准理解。宁可多花 2 分钟确认,也不要花 2 小时返工。
坚守最小修改原则。
- 一个 PR 只解决一个问题
- 不要做无关的重构(可以另开 PR)
- 结构清晰,命名准确,逻辑简洁
AI 生成代码后,必问的 3 个问题:
- 这段代码是否还有优化空间?(性能、可读性、边界处理)
- 是否所有错误/异常都被妥善处理?
- 是否有冗余代码或未使用的变量/导入?
📝 好的代码不是一次写出来的,是问出来的。
## PR Checklist
- [ ] 📸 已提供 UI 截图/功能演示
- [ ] 🧪 测试用例已添加并通过
- [ ] ✅ CI Workflow 全部通过
- [ ] 🤖 已与 AI 对齐需求理解
- [ ] 🎯 遵循最小修改原则,代码结构清晰
- [ ] 📝 已询问并处理代码优化建议| 规范 | 解决的问题 |
|---|---|
| 贴截图 | 避免"测试过吗?"的反复询问,建立 trust |
| 测试+CI | 防止 regression,降低 review 负担 |
| AI 对齐 | 减少"这不是我要的"的返工 |
| 最小修改+追问 | 保证代码可维护性,拒绝凑数代码 |
记住:PR 是沟通,不是交接。让 reviewer 轻松,就是让自己更快合入。
- 从最新
develop切release/x.y.z(在该分支 bump 版本与 CHANGELOG) - PR:
release/x.y.z→main,合并通过后 - 在 main tip 打并推送
v<version>,由 Actions 构建并发布 - 删除
release/x.y.z;Actions 自动 syncmain→develop(冲突或分支保护时会开chore/sync-develop-after-*PR)
Hotfix:从 main 拉分支 → 合入 main(需发补丁则打 tag)→ 再合入 develop。