使用 Github 操作標記 Git 存儲庫時在文件中寫入版本（= 標記）的良好做法

Question

我有一個包含一些源代碼和一些 Antora 文檔的存儲庫。 現在我正在嘗試編寫一個 github 操作來更新我的 antora.yml 中的版本並放置分支名稱。 當我不更改版本然后構建我的 antora 文檔時，我會在我的主分支和我的功能分支中使用version: main 。 然后 Antora 崩潰並出現Error: Duplicate nav in main 。

我寫了一個 github 動作來解決這個問題。 在推送時，我的操作會檢查我是否在 main 中，然后在我的 antora.yml 中提交version: main並推送遠程倉庫。 當我在功能分支中時，它會放置version: <branchname>並推送。 這行得通。

但是當我從主分支創建標簽時，我遇到了同樣的問題。 因為該標記不會更改任何源代碼，所以version: main被標記並出現在我的主分支中。 這會創建一個新的副本，它會破壞我的 Antora 構建。

我的問題是：我應該如何處理這個？ 我想在標簽中有例如version: v0.1.0但仍然version: main在我的主分支中。 我可以遵循一些好的做法嗎？ 我猜其他軟件項目也面臨着類似的問題。

我對 Github 操作的步驟：

# working for a feature branch
- name: Adjust version from 'main' to '<branchname>' if not already correct ... run on feature branch
  if: contains(github.ref, 'refs/heads/feat/')
  run: |
    BRANCH="${{github.ref}}"

    old="refs/heads/"
    BRANCH="${BRANCH//$old/}"

    old="/"
    new="__"
    BRANCH="${BRANCH/$old/$new}"

    old='version: main'
    new="version: $BRANCH"
    sed -i "s|$old|$new|g" docs/antora.yml

    cat docs/antora.yml
  shell: bash

# working for main branch
- name: Adjust version from '<branchname>' to 'main' if not already correct ... run on main branch
  if: github.ref == 'refs/heads/main'
  run: |
    oldPattern='version: '
    new='version: main'
    sed -i "/$oldPattern/s/.*/$new/" docs/antora.yml

    cat docs/antora.yml
  shell: bash

# not working for a tag
- name: Adjust version from '<branchname>' or 'main' to version 'v*' from tag
  if: startsWith(github.ref, 'refs/tags/v')
  run: |
    TAG="${{github.ref}}"

    old="refs/tags/"
    TAG="${TAG//$old/}"

    oldPattern='version: '
    new="version: $TAG"
    sed -i "/$oldPattern/s/.*/$new/" docs/antora.yml

    cat docs/antora.yml
  shell: bash
# https://github.com/marketplace/actions/add-commit
- name: Commit and push
  uses: EndBug/add-and-commit@v9
  with:
    author_name: sebastian
    author_email: sebastian@sommerfeld.io
    message: "[Actions Bot] refactor: set antora version to branchname"
    add: docs/antora.yml

標記時，工作流當然會因以下消息而崩潰：

Error: Error: fatal: You are not currently on a branch.
To push the history leading to the current (detached HEAD)
state now, use

    git push origin HEAD:<name-of-remote-branch>

如前所述：我應該如何解決這個問題？

1. 創建一個新分支
2. 更改分支內的版本號，然后提交+推送
3. 基於這個新的（臨時）分支創建一個標簽
4. 刪除臨時分支

我想這會起作用，但我相信一定有更好的方法。 有人有想法嗎？

Answer 1

我進行了一些研究並研究了基於主干的開發並為自己編寫了指南。

1. 主分支代表已准備好發布的最新穩定代碼庫。 更喜歡名稱 main 而不是 master。
2. 由於我的項目很小，基於主干是處理分支的首選方式。 沒有其他強制性分支。
3. 分支名稱需要一個前綴來顯示它們的意圖（例如，feat/）。 使用與 git 提交（文檔、專長、修復或重構）相同的前綴。 不需要其他前綴。 盡可能將 Jira 問題的 ID 添加到分支名稱中。 這樣做意味着一個 Jira 問題代表一個特性（對於大型特性，使用史詩的 ID）。
4. 接近發布時，會創建一個專門的發布分支，用於進行錯誤修復、文檔生成和微調。 發布分支在其名稱中包含版本（release/v0.1.1 或對於非生產版本 release/v0.1.1-SNAPSHOT）標簽是從此分支創建的。 在標記發布之前，來自發布分支的所有更改都合並到 main.js 中。 此外，一些精心挑選的提交可以合並到發布分支中。
5. 每次合並到 main 意味着該功能必須准備好生產！

你覺得這怎么樣？ 這符合一個共同的模式還是我自己有這個想法？

這至少應該有助於將分支名稱放入我的 antora-yml 中，因為現在我在標記之前有一個版本的分支。