Good practice to write the version (= tag) in a file when tagging a Git repo with Github Actions

Question

I have a repository with some source code and some Antora docs. Now I'm trying to write a github action that updates the version in my antora.yml and puts the branch name. When I don't change the version and then build my antora docs, I would habe version: main in my main branch and in my feature branch. Antora then crashes with Error: Duplicate nav in main .

I wrote a github action to sort this out. On push my action checks if I'm in main and then commits version: main in my antora.yml and pushes the the remote repo. When I'm in a feature branch, it puts version: <branchname> and pushes. This works.

But I get the same problem, when I create a tag from my main branch. Because the tag does not change any source code, the version: main is tagged and is present in my main branch. This creates a new duplicate which breaks my Antora build.

My question is: how should I handle this? I would like to have eg version: v0.1.0 in the tag but still version: main in my main branch. Are there some good practices I can follow? I guess other software projects face a similar issue.

My steps for Github Actions:

# 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

When tagging, of course the workflow crashes with this message:

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>

As said: how should I tackle this?

1. Create a new branch
2. Change the version number inside the branch, then commit + push
3. Create a tag based on this new (temporary) branch
4. Remove the temporary branch

I guess this would work, but I'm sure there must be a better way. Anyone got an idea?

Answer 1

I invested some research and took a look into trunk based development and wrote a guideline for myself.

1. The main branch represents the latest stable codebase which is ready for release. Prefer the name main over master.
2. Since my projects are small, trunk-based is the preferred way of handling branches. There are no other mandatory branches.
3. Branchnames need a prefix to show their intention (eg feat/). Use the same prefixes as with git commits (docs, feat, fix or refactor). There is no need for other prefixes. Add the IDs of the Jira issues to the branchname wherever possible. Doing this means one Jira issue represents one feature (for large features, use the ID of the epic).
4. When approaching a release, a dedicated release branch is created where bugfixes, docs generation and finetuning take place. The release branch contains the version in its name (release/v0.1.1 or for non-production releases release/v0.1.1-SNAPSHOT) The tag is created from this branch. Before tagging the release all changes from the release branch are merged into main. Addionally some hand-picked commits can be merged into the release branch.
5. Every merge into main means the feature must be production-ready!

What do you think of this? Does this fit a common pattern or am I on my own with this idea?

This should at least help with putting the branch-name into my antora-yml because now I have a branch for a version before tagging.