@lark-project/js-sdk/DEVELOPMENT_RELEASE.md

飞书项目 JSSDK 是飞书项目开放平台面向前端插件开发者提供的基于飞书项目内的开发工具包。 通过使用飞书项目 JSSDK，开发者可以方便的读取平台业务数据，如空间、工作项、字段等，当然也包括插件所运行环境的基础信息，如语言、地区、设备类型等。为开发者提供更高效的插件开发体验。

# js-sdk 开发与发布流程

本文只描述 `js-sdk` 仓库自身的开发与发布流程，不适用于开放平台前端 Bits 敏捷车。

## 包与分支

- 仓库：`dc/js-sdk`
- npm 包：`@lark-project/js-sdk`
- 正式 registry：`https://registry.npmjs.org/`
- 当前 `publishConfig.registry` 指向 npmjs
- 构建工具：Modern.js Module Tools
- 变更记录：`CHANGELOG.md`

## 本地开发

```bash
yarn
yarn build
```

`yarn build` 生成：

- `dist/types/index.d.ts`
- `dist/lib/index.js`
- `dist/es/index.js`

发布前需要确认公开类型已经体现在 `dist/types/index.d.ts` 中。

## 版本与变更记录

本仓当前是单包发布流程。发布前需要同步更新：

- `package.json` 的 `version`
- `CHANGELOG.md`

版本选择原则：

- 兼容新增类型或能力：递增 patch 或 minor；按本仓现有节奏优先 patch。
- 修复类型定义且不破坏 API：递增 patch。
- 破坏性类型调整：需要单独评审并写清迁移说明。

## 发布流程

```bash
yarn build
npm publish --registry=https://registry.npmjs.org/
npm view @lark-project/js-sdk@<version> version --registry=https://registry.npmjs.org/
git tag v<version>
git push origin v<version>
git add package.json CHANGELOG.md DEVELOPMENT_RELEASE.md
git commit -m "chore: release js-sdk <version>"
git push origin <branch>
```

`npm publish` 会触发：

- `prepublishOnly`: `modern build --platform`
- `prepare`: `modern build && husky install`

如果当前账号没有 npmjs 发布权限，需要先找 `@lark-project/js-sdk` 包 maintainer 添加权限；不要把未发布成功的版本打 release tag。

## 内网联调包

如确实需要先在内网联调，可以在确认权限和风险后发布到 BNPM：

```bash
npm publish --registry=https://bnpm.byted.org/
npm view @lark-project/js-sdk@<version> version --registry=https://bnpm.byted.org/
```

BNPM 发布不等价于 npmjs 正式发布，发布记录中必须明确 registry。

## 发布前检查清单

- `package.json` 版本未在目标 registry 中存在。
- `CHANGELOG.md` 已补充本次变更。
- `yarn build` 通过，并生成最新 `dist/` 产物。
- `npm publish --dry-run --registry=<target-registry>` 包内容符合预期。
- 目标 registry 中能查询到发布后的版本。