新消息：在Twitter和Mastodon取得專案更新

發佈流程

本文档旨在概述发布 cert-manager 新版本的流程。如果您想了解更多关于当前版本和未来版本的时间表，请查看支持的版本页面。

先决条件

⛔️ 如果您不满足以下所有条件，请勿继续进行发布流程

  1. 您尝试执行发布的相关的 testgrid 仪表板 不应失败。

  2. cert-manager 的 govulncheck GitHub Action 必须在您尝试发布的 branch 上通过。如有必要，请在本地运行 make verify-govulncheck。

  3. 发布过程大约需要 40 分钟。您必须有时间完成所有步骤。

  4. 您需要在 cert-manager 项目上拥有 GitHub admin 权限。要检查您是否拥有 admin 角色，请运行

    brew install gh
    gh auth login
    gh api /repos/cert-manager/cert-manager/collaborators/$(gh api /user | jq -r .login)/permission | jq .permission

    如果您的权限是 admin，那么您就可以继续了。要在 cert-manager 项目上请求 admin 权限，请开启一个 PR，并附上此处的链接。

  5. 您需要被添加到 GCP 项目 cert-manager-release 作为“编辑者”。要检查您是否拥有访问权限，请尝试打开Cloud Build 页面。要在 GCP 项目上获得“编辑者”权限，您需要成为维护者。如果您是维护者，请在 variables.tf 中的发布管理器列表中添加您的电子邮件地址，并开启一个 PR。

    您可以使用以下 PR 描述

    Title: Access to the cert-manager-release GCP project
    

    Hi. As stated in "Prerequisites" on the [release-process][1] page,
    I need access to the [cert-manager-release][2] project on GCP in
    order to perform the release process. Thanks!
    

    [1]: https://cert-manager.dev.org.tw/docs/contributing/release-process/#prerequisites
    [2]: https://console.cloud.google.com/?project=cert-manager-release

本指南适用于使用 make 发布的 cert-manager 版本，即 cert-manager 1.8 及更新的每个版本。

如果您需要发布 cert-manager 1.7 或更早的版本，请参阅较旧的版本。

工具设置

首先，请确保您拥有执行 cert-manager 发布所需的所有工具

  1. 安装 release-notes CLI

    go install k8s.io/release/cmd/release-notes@v0.13.0

  2. 安装我们的 cmrel CLI

    go install github.com/cert-manager/release/cmd/cmrel@latest

  3. 克隆 cert-manager/release 仓库

    # Don't clone it from inside the cert-manager repo folder.
    git clone https://github.com/cert-manager/release
    cd release

  4. 安装 gcloud CLI。

  5. 登入 gcloud

    gcloud auth application-default login

  6. 确保 gcloud 指向 cert-manager-release 项目

    gcloud config set project cert-manager-release
    export CLOUDSDK_CORE_PROJECT=cert-manager-release # this is used by cmrel

  7. 在此处获取一个未勾选任何 scope 的 GitHub 访问令牌。它仅由 release-notes CLI 使用，以避免 API 速率限制，因为它会逐个遍历所有 PR。

小版本发布

小版本发布是一个向后兼容的“功能”发布。它可以包含新功能和错误修复。

发布版本的流程

🔰 如果某个步骤缺失或已过时，请点击此页面右上角的 编辑此页面 按钮。

  1. 通过查看下表来回顾我们的发布术语。这将使您能够通过查看步骤的标题来了解要跳过哪些步骤，例如， （仅限最终版本） 表示此步骤仅在执行最终版本时才必须执行。

    发布类型git tag 示例
    初始 alpha 版本v1.3.0-alpha.0
    后续 alpha 版本v1.3.0-alpha.1
    初始 beta 版本v1.3.0-beta.0
    后续 beta 版本v1.3.0-beta.1
    最终版本v1.3.0
    （可选）补丁预发布1v1.3.1-beta.0
    补丁版本（或“点版本”）v1.3.1

  2. 通过将以下代码段复制到 shell 表中来设置 4 个环境变量

    export RELEASE_VERSION="v1.3.0-alpha.0"
    export START_TAG="v1.2.0"
    export END_REV="release-1.3"
    export BRANCH="release-1.3"

    注意：为了帮助您填写正确的值，请使用以下示例

    变量示例 1示例 2示例 2示例 3示例 4
    初始 alpha后续 alphabeta 版本最终版本补丁版本
    RELEASE_VERSIONv1.3.0-alpha.0v1.3.0-alpha.1v1.3.0-beta.0v1.3.0v1.3.1
    START_TAGv1.2.0v1.3.0-alpha.0v1.3.0-alpha.1v1.2.0*v1.3.0
    END_REVmastermasterrelease-1.3release-1.3release-1.3
    BRANCHmastermasterrelease-1.3release-1.3release-1.3

    *请勿在此处使用补丁（例如，没有 v1.2.3）。它必须是 v1.2.0：您必须使用属于您正在发布的发布分支的最新标签；在上面的示例中，发布分支是 release-1.3，并且该分支上的最新标签是 v1.2.0。

    注意：这 4 个变量在 release-notes 工具的 README 中进行了描述。为了方便起见，下表总结了您需要知道的内容

    变量描述
    RELEASE_VERSIONgit 标签
    START_TAG*“上一个”* 版本的 git 标签
    END_REV您的发布分支的名称（包括）
    BRANCH您的发布分支的名称

  3. （仅限最终版本）准备网站“升级说明”PR。

    确保具有新升级文档的 PR 已准备好在 cert-manager/website 上合并。例如，请参见 upgrading-1.0-1.1。

  4. （最终版本 + 补丁版本）准备网站“发布说明”PR。

    ⚠️ 此步骤可以提前完成。

    以下步骤需要在 master（最终版本）或 release-1.x（补丁版本）上进行。PR 将在发布后合并。

    使用下面的说明（Ctrl+F 并查找 github-release-description.md）转到“生成 github-release-description.md”部分。2. 删除“依赖项”部分。3. 对于 Markdown 文件中的每个项目符号，阅读更改日志条目，并检查其是否符合发布说明准则。如果您发现某个更改日志条目不符合准则，则

    • 转到该 PR 并编辑 PR 描述，以更改 release-note 代码块的内容。
    • 返回到发布说明页面，并将相同的更改复制到 release-notes.md 中（或重新生成该文件）。

    并将相同的更改复制到 release-notes.md 中（或重新生成该文件）。4. 通过参考之前的发布说明页面，添加“主要主题”和“社区”部分。5. 使用以下命令将 GitHub 问题编号和 GitHub 句柄（例如， #1234 或 @maelvls）替换为实际链接

    sed -E \
      -e 's$#([0-9]+)$[#\1](https://github.com/cert-manager/cert-manager/pull/\1)$g' \
      -e 's$@(\w+)$[@\1](https://github.com/\1)$g' \
      github-release-description.md >release-notes.md

    1. 将 release-notes.md 移动到网站仓库

      # From the cert-manager repo.
      mv release-notes.md ../website/content/docs/release-notes-1.X.md

    2. 向 content/docs/manifest.json 添加一个条目

      {
         "title": "Release Notes",
         "routes": [
      +    {
      +      "title": "v1.12",
      +      "path": "/docs/release-notes/release-notes-1.12.md"
      +    },

    3. 向文件 content/docs/release-notes/README.md 添加一行。

  5. （最终版本 + 补丁版本）准备网站“Bump Versions”PR。

    ⚠️ 此步骤可以提前完成。

    在该 PR 中

    1. （最终版本）更新supported-releases页面中的“支持的版本”部分。

    2. （最终版本）更新supported-releases页面上的“我们如何确定支持的 Kubernetes 版本”部分。

    3. （最终版本）更新scripts/gendocs/generate-new-import-path-docs中显示的 version。例如

      -LATEST_VERSION="v1.11-docs"
      +LATEST_VERSION="v1.12-docs"
      

      -genversionwithcli "release-1.11" "$LATEST_VERSION"
      +genversionwithcli "release-1.12" "$LATEST_VERSION"

    4. （最新次要版本的最終版 + 修補程式發布）在 variables.json 檔案中更新最新的 cert-manager 版本變數。

      -"cert_manager_latest_version": "v1.14.2",
      +"cert_manager_latest_version": "v1.14.3",

    5. （僅限最終版本）建立一份副本以凍結 docs/ 資料夾，從該副本中移除不適合版本化的頁面，並更新 manifest.json 檔案

      export RELEASE=1.15
      cp -r content/docs content/v${RELEASE}-docs
      rm -rf content/v${RELEASE}-docs/{release-notes,contributing}
      sed -i.bak "s|/docs/|/v${RELEASE}-docs/|g" content/v${RELEASE}-docs/manifest.json
      jq < content/v${RELEASE}-docs/manifest.json >/tmp/manifest \
        'del(.routes[0].routes[] | select(.title | test("Releases|Contributing")))'
      mv /tmp/manifest content/v${RELEASE}-docs/manifest.json

    6. （最終版 + 修補程式發布）更新API 文件和CLI 文件

      # From the website repository, on the master branch.
      ./scripts/gendocs/generate

  6. 檢查 origin 遠端是否正確。為此，請執行以下命令，並確保它傳回上游的 https://github.com/cert-manager/cert-manager.git

    # Must be run from the cert-manager repo folder.
    git remote -v | grep origin

    應該會顯示

    origin  https://github.com/cert-manager/cert-manager (fetch)
    origin  https://github.com/cert-manager/cert-manager (push)

  7. 將自己置於正確的分支上

    • （初始 alpha 和後續 alpha）：將自己置於 master 分支上

      git checkout master
      git pull origin master

    • （僅限初始 beta）發布分支尚不存在，因此讓我們建立並推送它

      # Must be run from the cert-manager repo folder.
      git checkout master
      git pull origin master
      git checkout -b release-1.12 master
      git push origin release-1.12

      GitHub 權限：只有當您在 cert-manager 儲存庫上擁有 admin GitHub 權限來建立或推送分支時，git push 才會生效，請參閱先決條件。如果您沒有此權限，則必須開啟 PR 以將 master 合併到發布分支中，並等待 PR 檢查通過。

    • （後續 beta、修補程式發布和最終版本）：將自己置於發布分支上

      git checkout release-1.12
      git pull origin release-1.12

      您不需要快轉分支，因為已使用 /cherry-pick release-1.0 合併了內容。

      關於程式碼凍結的注意事項

      第一個 beta 版本會開始新的「程式碼凍結」期間，該期間會持續到最終版本。在程式碼凍結之前，我們會將所有內容從 master 快轉到發布分支中。

      在程式碼凍結期間，我們會像平常一樣繼續將 PR 合併到 master 中。

      我們不會為第二個（和後續）beta 版本將 master 快轉到發布分支中，而只會 /cherry-pick release-1.0 應該是後續 beta 版本一部分的修正。

      我們不會為修補程式發布和最終版本進行快轉；相反地，我們會使用 /cherry-pick release-1.0 命令準備這些版本。

    關於分支保護的注意事項：發布分支受到GitHub 分支保護的保護，該保護由 Prow 自動設定。這會防止任何人不小心直接將變更推送至這些分支，即使是儲存庫管理員也一樣。如果您因為某些原因需要快轉發布分支，則應使用GitHub 分支保護 Web UI刪除該發布分支的分支保護。這只是為了讓您更新分支的臨時變更。Prow 將在 24 小時內重新套用分支保護。

  8. 在本機建立新版本所需的標籤，並將其推送到上游（開始 cert-manager 建置）

    echo $RELEASE_VERSION
    git tag -m"$RELEASE_VERSION" $RELEASE_VERSION
    # be sure to push the named tag explicitly; you don't want to push any other local tags!
    git push origin $RELEASE_VERSION

    注意：只有當您在 cert-manager 儲存庫上擁有 admin GitHub 權限來建立或推送分支時，git push 才會生效，請參閱先決條件。如果您沒有此權限，則必須開啟 PR 以將 master 合併到發布分支中，並等待 PR 檢查通過。

    注意 2：對於 cert-manager 的最新版本，正在推送的標籤會觸發 Google Cloud Build 作業開始，並使用 gcb/build_cert_manager.yaml 中的步驟開始建置。具有 GCP 上 cert-manager-release 專案存取權的使用者應該能夠在 GCB 建置歷史記錄中檢視記錄。

  9. 僅限 (1.12、1.13 和 1.14)

    在此步驟中，我們確保第三方可以匯入 Go 模組 github.com/cert-manager/cert-manager/cmd/ctl。

    首先，建立一個臨時分支。

    # Must be run from the cert-manager repo folder.
    git checkout -b "update-cmd/ctl/$RELEASE_VERSION"

    其次，使用我們剛剛建立的標籤更新 cmd/ctl 的 go.mod

    # Must be run from the cert-manager repo folder.
    cd cmd/ctl
    go get github.com/cert-manager/cert-manager@$RELEASE_VERSION
    cd ../..
    

    make tidy
    git add "**/go.mod" "**/go.sum"
    git commit --signoff -m"Update cmd/ctl's go.mod to $RELEASE_VERSION"

    然後，將分支推送到您的 cert-manager 分支。例如

    # Must be run from the cert-manager repo folder.
    gh repo fork --remote-name fork
    git push -u fork "update-cmd/ctl/$RELEASE_VERSION"

    然後，開啟 PR 以合併該變更，並使用以下命令返回發布分支

    gh pr create \
      --title "[Release $RELEASE_VERSION] Update cmd/cmctl's go.mod to $RELEASE_VERSION" \
      --body-file - --base $BRANCH <<EOF
    This PR cmd/cmctl's go.mod to $RELEASE_VERSION as part of the release process.
    

    **To the reviewer:** the version changes in \`go.mod\` must be reviewed.
    

    \`\`\`release-note
    NONE
    \`\`\`
    EOF

    等待 PR 被合併。

    最後，為 cmd/ctl 模組建立標籤

    # Must be run from the cert-manager repo folder.
     git fetch origin $BRANCH
     git checkout $BRANCH
     git pull --ff-only origin $BRANCH
     git tag -m"cmd/ctl/$RELEASE_VERSION" "cmd/ctl/$RELEASE_VERSION" origin/$BRANCH
     git push origin "cmd/ctl/$RELEASE_VERSION"

    注意：我們需要這樣做的原因在 Stack Overflow 上說明：如何管理子模組的版本

  10. 在本節中，我們將建立 GitHub 發布的描述。

    注意：此步驟是關於建立將會複製貼上到 GitHub 發布頁面中的描述。網站上「發行說明」頁面的建立會在之前的步驟中完成。

    1. 檢查所有 4 個環境變數是否已準備就緒

      echo $RELEASE_VERSION
      echo $START_TAG
      echo $END_REV
      echo $BRANCH

    2. 使用以下命令產生 github-release-description.md

      # Must be run from the cert-manager folder.
      export GITHUB_TOKEN=$(gh auth token)
      git fetch origin $BRANCH
      export START_SHA="$(git rev-list --reverse --ancestry-path $(git merge-base $START_TAG $BRANCH)..$BRANCH | head -1)"
      release-notes --debug --repo-path cert-manager \
        --org cert-manager --repo cert-manager \
        --required-author "cert-manager-prow[bot]" \
        --markdown-links=false \
        --output github-release-description.md

      GitHub 權杖不需要任何範圍。僅需要權杖以避免匿名 API 使用者受到的速率限制。

    3. 在頂端新增一句摘要。

    4. （僅限最終版本）撰寫「社群」章節，遵循過去發布版本的範例，例如 v1.12.0。如果任何使用者沒有做出程式碼貢獻，但在其他方面（測試、PR 討論等）提供了幫助，請務必在這裡感謝他們！

  11. 檢查在您推送標籤時自動觸發的建置是否已完成，並傳送有關發布的 Slack 訊息

    1. 將第一則 Slack 訊息傳送至 #cert-manager-dev

      發布 1.2.0-alpha.2 🧵

    2. 檢查建置是否在 GCB 建置歷史記錄中完成。

      🔰 請快速查看建置記錄，因為它可能包含我們忘記隱藏的一些未編輯資料。我們會盡力確保敏感資料已正確編輯，但有時我們會忘記更新此內容。

    3. 複製建置記錄 URL，並回覆第一則訊息，傳送第二則包含 Cloud Build 作業連結的 Slack 訊息。例如，訊息可能如下所示

      cmrel makestage 建置記錄：https://console.cloud.google.com/cloud-build/builds/7641734d-fc3c-42e7-9e4c-85bfc4d1d547?project=1021342095237

  12. 執行 cmrel publish

    1. 執行 cmrel publish 試執行，以確保所有已暫存的資源都有效。執行以下命令

      # Must be run from the "cert-manager/release" repo folder.
      cmrel publish --release-name "$RELEASE_VERSION"

      您可以透過按一下此命令輸出中的 Google Cloud Build URL 來檢視進度。

    2. 在建置執行時，回覆第一則訊息，傳送第三則 Slack 訊息

      追蹤 cmrel publish 試執行建置：https://console.cloud.google.com/cloud-build/builds16f6f875-0a23-4fff-b24d-3de0af207463?project=1021342095237

    3. 現在實際發布發布成品。以下命令會將成品發布到 GitHub、Quay.io 以及我們的helm 圖表儲存庫

      # Must be run from the "cert-manager/release" repo folder.
      cmrel publish --nomock --release-name "$RELEASE_VERSION"

      ⏰ 完成後將會有

      1. GitHub 上 cert-manager 的草稿發布
      2. 包含新 Helm 圖表的提取請求

    4. 在建置執行時，回覆第一則訊息，傳送第四則 Slack 訊息

      追蹤 cmrel publish 建置：https://console.cloud.google.com/cloud-build/builds/b6fef12b-2e81-4486-9f1f-d00592351789?project=1021342095237

  13. 發布 GitHub 發布

    1. 造訪 GitHub 草稿發布，並貼上您先前產生的發行說明。您將需要手動編輯內容以符合先前發布版本的樣式。尤其，記得移除與套件相關的變更。

    2. （僅限初始 alpha、後續 alpha 和 beta）勾選「這是一個預先發布版本」方塊。

    3. （最終版本和修補程式發布）勾選「設定為最新版本」方塊。

    4. 按一下「發布」以讓 GitHub 發布生效。

  14. 合併包含 Helm 圖表的提取請求

    重要事項：此 PR 目前只能由 Venafi 員工合併，但我們正努力盡快修復此問題。變更此內容需要我們提出遷移 Helm 圖表儲存位置的計劃，並確保我們不會中斷任何人的作業。

    cert-manager 的 Helm 圖表是使用 Cloudflare 頁面提供的，Helm 圖表檔案和中繼資料儲存在Jetstack 圖表儲存庫中。cmrel publish --nomock 步驟（以上）將會在該儲存庫中建立 PR，您現在必須依以下步驟檢閱並合併：

    1. 造訪提取請求
    2. 檢閱變更
    3. 修正任何失敗的檢查
    4. 測試圖表
      1. 從提取請求下載圖表 tarball
      2. 啟動新的本機 Kind 叢集 kind create cluster --name release
      3. 將 helm 圖表安裝到 kind 叢集 helm install cert-manager ./cert-manager-v0.15.0.tgz --set crds.enabled=true -n cert-manager
      4. 確保安裝成功且所有元件都在執行
      5. 關閉 kind 叢集 kind delete cluster --name release
    5. 合併 PR
    6. 檢查 cert-manager Helm 圖表是否在 ArtifactHUB 上可見。

  15. （最終版 + 修補程式發布）合併 4 個網站 PR

    1. 合併您先前建立的「發行說明」、「升級說明」和「凍結和更新版本」的 PR。

    2. 透過按一下這裡建立 PR「將 release-next 合併到 master」。

      如果您看到標籤 dco-signoff: no，請在 PR 上新增帶有以下內容的註解

      /override dco

      此命令是必要的，因為某些合併提交是由機器人撰寫的，且沒有 DCO 簽署。

  16. 僅限 (1.14 和更低版本)

    為 cmctl 開啟一個Homebrew 公式更新的 PR。

    ℹ️ 如果您發佈的是 cert-manager 的 latest 版本，PR 會自動建立，在這種情況下，可以跳過此步驟。但如果您發佈的是先前版本的修補程式，則不能跳過。

    假設您已安裝 brew，您可以使用 brew bump-formula-pr 命令來執行此操作。您需要新的標籤名稱和該標籤的 commit hash。請參閱 brew bump-formula-pr --help 以獲取最新的詳細資訊，但命令格式將如下所示：

    brew bump-formula-pr --dry-run --tag v0.10.0 --revision da3265115bfd8be5780801cc6105fa857ef71965 cmctl

    將標籤和修訂版本替換為新的版本。

    Homebrew 團隊需要時間審核。一旦針對 https://github.com/homebrew/homebrew-core 開啟 pull request 後，請繼續執行後續的發佈步驟。

  17. 在 Slack 上回覆第一則訊息。切換「同時發送至 #cert-manager-dev」的核取方塊，以便訊息清晰可見。也將訊息轉貼到 #cert-manager。

    https://github.com/cert-manager/cert-manager/releases/tag/v1.0.0 🎉

  18. （僅限最終版本）向世界展示發佈版本

    1. 傳送電子郵件至 cert-manager-dev@googlegroups.com，並加上 release 標籤（範例）。

    2. 在 cert-manager Twitter 帳戶上發送推文！登入詳細資訊在 Jetstack 的 1password 中（目前）。（推文範例）。請務必讓 @JetstackHQ 轉發！

    3. 從 cert-manager Mastodon 帳戶發送 toot！登入詳細資訊在 Jetstack 的 1password 中（目前）。（Toot 範例）

  19. 繼續執行發佈後的「測試和發佈」步驟

    1. （僅限初始 beta 版本）在 cert-manager/testing 上建立 PR，以便將新版本新增至我們的定期 ProwJobs 清單。請使用此 PR 作為範例。您需要執行 make prowgen 命令來產生新的設定檔。

    2. （僅限最終版本）在 cert-manager/testing 上建立 PR，從 prow 設定中移除任何不支援的版本。

    3. （僅限最終版本）在 cert-manager/testing 中，檢查 milestone_applier 設定，以便將在 master 上新提出的 PR 套用到下一個新版本的里程碑。

      同時檢查發佈分支的必要狀態檢查和 testgrid 儀表板設定。

      如果下一個版本的 里程碑不存在，請先建立它。如果您認為剛發佈的版本里程碑已完成，請將其關閉。

    4. 針對 Krew 索引開啟 PR，例如這個 PR，提升我們的 kubectl 外掛程式的版本。只有在 cmctl/kubectl 外掛程式功能發生重大變更或在新主要版本的首次發佈之後，這才可能值得。

    5. 建立新的 OLM 套件並發佈到 OperatorHub

      cert-manager 可以使用 Operator Lifecycle Manager (OLM) 進行安裝，因此我們需要為每個 cert-manager 版本建立 OLM 套件，並將它們發佈到 operatorhub.io 和 RedHat OpenShift 的對應套件索引。

      遵循cert-manager OLM 發佈流程，並在發佈後，驗證 cert-manager OLM 安裝指示仍然有效。

舊版本

以上指南僅適用於 v1.8 及更新版本的 cert-manager。

較舊的版本是使用 Bazel 建置的，而建置流程中的這種差異反映在發佈流程中。

cert-manager 1.6 和 1.7

請遵循 GitHub 上發佈流程的這個舊版本，而不是本網站上的指南。

最顯著的差異是您將呼叫 cmrel stage 而不是 cmrel makestage。您應該可以使用最新版本的 cmrel 來執行發佈。

cert-manager 1.5 和更早版本

如果您發佈的是 1.5 或更早版本，您也必須確保安裝不同版本的 cmrel。

在您安裝 cmrel 的步驟中，您需要改為執行以下命令

go install github.com/cert-manager/release/cmd/cmrel@cert-manager-pre-1.6

這將確保您使用的 cmrel 版本與您要發佈的 cert-manager 版本相容。

此外，當您檢出 cert-manager/release 儲存庫時，您應該務必檢出該儲存庫中的 cert-manager-pre-1.6 標籤

git checkout cert-manager-pre-1.6

除了不同的 cert-manager/release 標籤和 cmrel 版本之外，您可以遵循與 1.6 和 1.7 相同的相同較舊版本發佈文件，只需記住變更您安裝的 cmrel 版本！

附註

  1. 可能會建立一個或多個「修補程式預發行版」，以允許社群在一般提供修正程式之前，自願測試錯誤修正或安全性修正。修補程式預發行版必須使用 -beta 後綴。↩