Embed lib/*.mq.md in binary; marqdo version --check; public writeback/subtask pages; restore /vscode-extension/ ignore. VSIX built from branch vscode-extension only (see doc/design/vscode-extension-commit.md). Co-authored-by: Cursor <cursoragent@cursor.com>
2.8 KiB
2.8 KiB
VS Code 扩展 — 分支与提交约定
| 状态 | 强制约定(勿在 main 提交扩展源码) |
| 扩展分支 | vscode-extension |
| 设计说明 | vscode-extension.md |
1. 原则(必读)
| 分支 | 是否跟踪 vscode-extension/ |
|---|---|
main |
否 — .gitignore 含 /vscode-extension/ |
vscode-extension |
是 — 扩展唯一源码所在分支 |
禁止在 main 上:
- 删除
.gitignore里的/vscode-extension/ git add vscode-extension/- 把扩展目录「合并进 main」以便发版
发版时从 vscode-extension 分支检出扩展目录打 VSIX(见 §4),不是把扩展提交进 main。
2. 日常开发(扩展)
git fetch origin
git checkout vscode-extension
cd vscode-extension && npm ci && npm run compile
改语法、CLI 检测、扩展版本 → 只在 vscode-extension 分支提交:
git add vscode-extension/
git commit -m "vscode-extension: <简要说明>"
git push origin vscode-extension
3. 日常开发(CLI / 语言)
在 main 上改 src/、lib/、public/、tests/ 等;不要顺带提交 vscode-extension/。
若本地为了调试 checkout 过扩展目录,工作区里可以有 vscode-extension/ 文件夹,但应被 ignore,且 git status 不应出现该目录下文件。
4. 发版(CLI tag + VSIX)
main:打 tag(如v0.1.2),CI 构建marqdo.exe等。- VSIX:Release 工作流在 tag 构建时执行:
git fetch origin vscode-extension git checkout origin/vscode-extension -- vscode-extension cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package - 本地脚本
scripts/release-windows.ps1同样假定:先git checkout origin/vscode-extension -- vscode-extension(或已在vscode-extension分支),再打 VSIX。
扩展版本号与最低 CLI 要求写在 vscode-extension/package.json 与分支 README,不要在 main 的 CHANGELOG 里冒充已合并扩展源码。
5. 给 Agent / 协作者
执行「更新 VS Code 插件」类任务时:
- 切到或基于
vscode-extension分支改vscode-extension/** - 不要移除
main上.gitignore的/vscode-extension/ - 不要在
main的 release 提交里包含vscode-extension/package-lock.json等大文件 - 仅需在
main更新时:改doc/design/vscode-extension.md、Release 说明、本文件 — 指针文档即可
6. 历史说明
v0.1.2 准备阶段曾误将 vscode-extension/ 并入 main(并删除 ignore),导致推送体积过大。已恢复:扩展仅 vscode-extension 分支;main 只保留本约定与设计指针。