# 发布到 npm

本仓库使用 [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)：GitHub Actions 通过 OIDC 获取短期发布权限，不需要 npm 密码、`NPM_TOKEN` 或 `NODE_AUTH_TOKEN` secret。已经存在的 npm 包 `dsh-discussions-digest` 可以直接配置该方式。

流程由 `.github/workflows/publish.yml` 定义：推送 `v*` tag → 检查 tag 与 package/lockfile 版本一致、提交属于 main → 安装依赖、测试、构建并上传 tarball → 等待 `npm` environment 审批 → 发布同一个 tarball。普通 main push 和 PR 不会发布。正式版本使用 npm `latest`，含预发布后缀的版本使用 `next`。

## 一次性配置 GitHub

1. 将发布 workflow 提交并推送到 `main`。
2. 打开仓库 **Settings → Environments → New environment**，名称填写 **`npm`**。
3. 在 **Required reviewers** 添加自己，保存规则。个人独立维护时不要开启 **Prevent self-review**，否则你不能批准自己推送 tag 触发的发布。
4. 在 **Deployment branches and tags** 选择 **Selected branches and tags**，添加 **Tag** 类型规则 **`v*`**。不要只允许 `main` 分支，因为发布运行来自 tag。
5. 此流程无需添加 npm secrets。

务必在推送版本 tag 前设置 Required reviewers。仅在 YAML 中写 `environment: npm` 不会自动要求人工确认；GitHub 甚至会自动创建没有保护规则的同名环境。公共仓库可以使用所需审批功能，私有仓库取决于 GitHub 套餐。参见 [GitHub Environment 配置文档](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)。

## 一次性配置 npm

登录拥有此包维护权限的 npm 账号，打开 **Packages → dsh-discussions-digest → Settings → Trusted publishing → Add trusted publisher → GitHub Actions**，填写：

| 字段 | 值 |
| --- | --- |
| Organization or user | `kristol07` |
| Repository | `dsh-discussions-digest` |
| Workflow filename | `publish.yml`（只填文件名） |
| Environment name | `npm` |
| Allowed actions | 允许直接发布的 **`npm publish`** |

环境名称必须与 workflow 一致。新配置可能默认只允许 staged publishing；本 workflow 执行直接 `npm publish`，需要明确允许它。发布前的人工确认由 GitHub Environment 承担。OIDC 要求 npm CLI 至少 11.5.1；workflow 使用 Node 24 和 npm 11。参见 [npm 官方配置说明](https://docs.npmjs.com/trusted-publishers/)。

## 发布当前 0.4.0

先完成上述配置，将包括 workflow 的提交推送到 main，然后在仓库目录运行：

```powershell
git switch main
git pull --ff-only
git status --short
# 确认工作区干净，package.json 和 package-lock.json 都是 0.4.0。
git tag -a v0.4.0 -m "Release 0.4.0"
git push origin v0.4.0
```

打开 **Actions → Publish to npm**，等待 `Validate, test and pack` 成功。在摘要中核对版本、commit 与 `latest`/`next`，必要时下载 `npm-package` artifact 检查内容，再点击 **Review deployments → npm → Approve and deploy**。审批后自动发布；不需要另外创建 GitHub Release。

发布成功后检查 registry：

```powershell
npm view dsh-discussions-digest@0.4.0 version
npm view dsh-discussions-digest dist-tags --json
```

不要在当前已发布的 `v0.1.0-rc.1` tag 上补触发或移动标签。已有 npm name/version 不能覆盖；重跑前先检查目标版本是否已经发布。若尚未发布且只是权限或配置错误，可修正平台设置后在 Actions 重跑失败的 job。若需要修改 workflow 或代码，使用新的版本和 tag。

## 后续版本

```powershell
npm version 0.4.1 --no-git-tag-version
# 更新 CHANGELOG 和 README，检查后提交并推送 main。
git add package.json package-lock.json CHANGELOG.md README.md
git commit -m "release: prepare 0.4.1"
git push origin main
git tag -a v0.4.1 -m "Release 0.4.1"
git push origin v0.4.1
```

在 Actions 中完成同样的人工审批。测试版可用 `0.5.0-beta.1` 和 `v0.5.0-beta.1`，会发布到 `next`，不会替换 `latest`。发布行为不会自动修改 DSH 兼容版本或台账 schema，也不会自动更新 CHANGELOG。

## 手动发布备用方式

如果暂时不用 Actions，可以在确认的发布提交上自行执行：

```powershell
npm login --registry=https://registry.npmjs.org
npm ci
npm test
npm pack --ignore-scripts
npm publish .\dsh-discussions-digest-0.4.0.tgz --access public --tag latest
```

在浏览器/终端完成 npm 要求的登录与二次验证。预发布版本把版本号换成对应值，并使用 `--tag next`。手动发布与 Actions 二选一，不要对同一个版本执行两次。手动方式不包含 Actions 的 Environment 审批及该 workflow 生成的 provenance。

## English

Push a version tag matching `package.json`, such as `v0.4.0`, after merging the workflow and release changes into `main`. Configure the GitHub environment **npm** with required reviewers and the tag rule **v*** before pushing the tag. Solo maintainers must leave **Prevent self-review** disabled. Configure npm's GitHub trusted publisher with user **kristol07**, repository **dsh-discussions-digest**, workflow **publish.yml**, environment **npm**, and allow direct **npm publish**. No npm password or token secret is needed.

The workflow verifies metadata and main ancestry, tests/builds the package, and uploads a tarball. Review the run summary and approve the deployment before the publish job can run. It publishes the tested artifact with provenance; normal versions use **latest**, prereleases use **next**. A successful publish cannot be overwritten. Check npm before retrying a run, and use a new version if code or workflow changes are needed.