KsADK
贡献

发布流程

公开发布分为维护者审核、GitHub 导入、Pages、release 和 PyPI/TestPyPI。

发布前

make public-review
make public-publish-check PUBLIC_PUBLISH_PHASE=pre-publish V=0.6.7

GitHub

维护者 review 通过后，从已审核的 GitHub main commit 创建 tag 和 release。 不要从未同步的候选分支直接创建公开 release。

PyPI

PyPI metadata 指向：

  • Repository: https://github.com/kingsoftcloud/ksadk-python
  • Documentation: https://kingsoftcloud.github.io/ksadk-python/

上传凭证不进入仓库。推荐使用 PyPI Trusted Publishing / GitHub OIDC； 如需临时 token，也只能放在发布系统 secrets 或维护者本地环境中。

真正执行 make publish 或 make publish-test 前，必须填好 docs/maintainer-approval-record.md。该记录需要包含已审核 commit SHA、 发布策略和维护者签署。

正式发布 workflow

正式发布走 .github/workflows/publish-pypi.yml，由 GitHub Release published 或 workflow_dispatch 触发。

新增

该 workflow 取代了过去的手动 make publish 上传，正式包统一通过 OIDC Trusted Publishing 上传到 PyPI。

workflow 执行步骤如下：

  1. 同步前端静态资源：make sync-ksadk-web-static，默认从 @kingsoftcloud/ksadk-web@latest 拉取 dist-ksadk 解包到打包目录； 通过 workflow_dispatch 触发时可传 ksadk_web_version 输入指定版本 （如 1.2.3）。
  2. 发布前预检：make public-preflight，串起 public-audit、 public-test、docs-site-build 以及 public-build-check。
  3. 构建与内容检查：public-build-check 内执行 uv build 并 twine check dist/*，校验 wheel 与 sdist 元数据。
  4. OIDC 上传：用 pypa/gh-action-pypi-publish 通过 Trusted Publishing 上传，job 运行在 pypi environment 并声明 id-token: write。
# .github/workflows/publish-pypi.yml 触发与权限要点
on:
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      ksadk_web_version:
        description: KsADK Web npm version to bundle
        required: false
        default: latest
permissions:
  id-token: write   # OIDC Trusted Publishing 必需

不要配 PYPI_API_TOKEN

正常发布路径完全走 OIDC Trusted Publishing，仓库和 workflow secrets 里都不需要 PYPI_API_TOKEN。只有 Trusted Publishing 不可用的回退 场景才考虑临时 token，且必须放在 GitHub environment secrets 中。

本地复刻发布前预检（示例版本号按当前发版替换）：

make sync-ksadk-web-static
make public-preflight
make public-publish-check PUBLIC_PUBLISH_PHASE=pre-publish V=0.6.7

本页导航

发布前GitHubPyPI正式发布 workflow