使用 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 中，因为现在我在标记之前有一个版本的分支。