Files
marqdo/doc/design/vscode-extension-commit.md
T
cflmyandCursor 2e65c055b8 Release v0.1.2: embedded stdlib, docs, and extension branch policy.
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>
2026-08-07 09:41:53 +08:00

2.8 KiB
Raw Blame History

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)

  1. main:打 tag(如 v0.1.2),CI 构建 marqdo.exe 等。
  2. 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
    
  3. 本地脚本 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 插件」类任务时:

  1. 切到或基于 vscode-extension 分支改 vscode-extension/**
  2. 不要移除 main 上 .gitignore 的 /vscode-extension/
  3. 不要在 main 的 release 提交里包含 vscode-extension/package-lock.json 等大文件
  4. 仅需在 main 更新时:改 doc/design/vscode-extension.md、Release 说明、本文件 — 指针文档即可

6. 历史说明

v0.1.2 准备阶段曾误将 vscode-extension/ 并入 main(并删除 ignore),导致推送体积过大。已恢复:扩展仅 vscode-extension 分支;main 只保留本约定与设计指针。