Good practices for release management

[josecelano]

We forked the repo from the official Typescript GitHub Action Template. On its README it explains how to publish to a distribution branch.

We have been discussing the release process. We agreed that each commit should build the app (in the dist folder).

But the template and the GitHub Actions toolkit docs promote the use of "releases/v1, releases/..." branches.

Currently, we are not using releases branches but we should know exactly why they are used for.

We are using tags and we include the build app (dist folder) on each commit, that seems to be enough for users to use any specific version they want to use: concrete commit hash or tag release (following semantic versioning).

It seems both methods are acceptable:

• Using tag for release management
• Using branches for release management

But on other part of the official documentation, It seems GitHub promotes not to include the built app on each commit, but only on tag for releases. I suppose you can do this with tag releases of branch releases.

So we should review:

1. Whether we continue using tag releases or we switch to branch releases.
2. If we include the built app in all commit or only in tags.

I do not see any reason to change what we are doing right now. In fact, using an concrete commit in a workflow can be a fast way to apply an action patch without releasing a new version. Or maybe that's exactly the reason why we should not do it, because it forces you to use semantic versioning. In that case, branches seem to be a faster way to apply fixes and guarantee therelease inmutability.

cc @da2ce7 @yeraydavidrodriguez

LINKS

• GitHub docs: Releasing and maintaining actions
• GitHub docs: Using release management for actions
• TpeScript GitHub Action Template: Publish to a distribution branch
• GitHub Actions toolkit: Action Versioning

[josecelano]

It seems the main purpose of "release/vX" branches is only to test the release before publishing it:

https://docs.github.com/en/actions/creating-actions/about-custom-actions#using-tags-for-release-management

Create and validate a release on a release branch (such as release/v1) before creating the release tag (for example, v1.0.2).

But I think we can get the same result using a tag. That's what we are doing right now. We create a new tag, for example: v1-beta before releasing the v1 version. I suppose the only difference is we use tags instead of branches.

[josecelano]

I've asked on the GitHub Action Template repo.

[josecelano]

I've also asked on the Community Forum about how GitHub uses tag or branches when it imports an action to be used in a workflow.

[josecelano]

After reading again the documentation I think I've found the reason why at some point you need release branches anyway.

1. You release the version v1 which currently is the 1.0.0.
2. You add some new features without breaking compact: 1.1.0. You update v1 tag.
3. You create a new major release: 2.0.0 and v2 tags.
4. You find a bug in 1.1.0 and create a new release to fix it: 1.1.1.

At this point you want people using ...@v1 version to get the patch and you also want to apply the patch to v2 if needed. In order to apply the patch to v1 you need to create a new branch.

It basically the problem of maintaining different major versions. Instead of waiting until you find a bug in the major version, you can create the servicing branch even before releasing the final version. That way:

• You already have the branch ready to be fixed if needed.
• You can use that branch as a beta version. You do not need to create a specific tag like v1-beta
• You can apply some protection rules to the release branches in order to make them immutable.

It seems the standard name for those branches is: releases\v1, etcetera.

I was trying to find out if that branch name has a special treatment on GitHub but I have not found anything. You can use an action using a branch name, so I guess you only need to do it like this:

- name: YOUR_STEP_NAME
  uses: Nautilus-Cyberneering/git-queue@releases/v1

This comment should answer question 1 in my first comment (Whether we continue using tag releases or we switch to branch releases).

In our case, it has an extra side effect. Since we are generating releases automatically with a workflow, when you create the v1 tag, that is going to create a release. If you only create the new branch releases\v1, that is not going to create any release. If we want to create a public beta release then I would suggest continuing using beta tags like v1-beta. I would say that for the first internal tests we could use the branch and for public testing, we could officially release a beta verion.

[josecelano]

In our latest meeting, we were discussing again this topic. We agree that maybe using GitFlow could be a good idea for some reasons:

1. At some point we will need to maintain different versions.
2. It is a very common and well-known It branching strategy so we do not need to explain it to external collaborators.
3. In the future we want to apply some protection rules to important branches like main or release branches.

Some of the extra ideas we want to apply on top of GitFlow:

• Create branch protection rules for release branches.
• Create a GitHub merge script like this one. We are not using GitHub merge button anymore because for example "Rebase and merge" button does not keep the original commit GPG signatures.
• We can use the merge script to merge into important branches like main or releases.
• In the long run, we want only bots to be able to merge into important branches.
• For the time being, instead of using a bot to merge into main we are going to start using a different Git account. I proposed to use our bot account. I suppose we could add two new SSH keys for @da2ce7 and @josecelano and also a different signing GPG subkey.

I think we could create the branches for GitFlow before publishing the first stable release.

[josecelano]

I found this article (in Spanish, by @ulisesantana) that explains how to set up Git to use different committer info depending on the project folder. Based on Git config file includes.

Thanks @ulisesantana

[da2ce7]

For the time being, instead of using a bot to merge into main we are going to start using a different Git account. I proposed to use our bot account. I suppose we could add two new SSH keys for @da2ce7 and @josecelano and also a different signing GPG subkey.

You can upload multiple SSH and GPG keys to a single account. I think that each of us can just make another signing-only GPG, and we upload it to the bot's account; we can specify the GPG ID to be something like: Nautilus Cyberneering [bot] [cameron].

[josecelano]

OK, in this case, it makes more sense. I was thinking about the other case, when we want to import a signing GPG subkey in a different repository and we want any of us to create/revoke those keys.

And that makes me think that maybe it's not a good idea a central bot. Maybe each admin should use their own bot. If an admin leaves the organization you have to "remove" all their bots GPGP keys from the secrets, the same way you remove them from the admin panel. But with what you proposed we could remove only the admin GPG key from the bot account.

I had a similar discussion some years ago with a friend of mine regarding having "central company master accounts". It makes it easier to handle secrets but you have to change the secret in all places where it was used. In our case, if all admins had access to the same primary GPG key, we would have to create a new primary key and replace all the singing subkeys in all repos/environemnts. If we only use bots that mirror admin accounts we only need to change repos/envs where their keys were being used. But we need to keep track of where the admin bot's keys are being used.

I think allowing you to have a bot account linked to your primary GitHub account would be also a nice feature to have, as @liyishuai proposed here.

In summary, we have some alternatives.

• One central bot
  • Sharing primary GPG keys between all org admins. Change all when an admin leaves.
  • One bot GPG key for each admin. Change only their GPGP keys when an admin leaves.
• Each admin has their own bot. Change only their GPGP keys when an admin leaves. We can use the central bot to keep track of org's contributions (commit author) but without signing. I think in this case commits would appear as "partially verified".

I think I prefer your solution for both merging scripts and signing commits in GitHub Actions workflows.

[josecelano]

I started using the bot the merge into the main repos this way:

1. Merge from the fork with ff.
2. Ammend the commits to change the committer to use the bot.

See nautilus-cyberneering/chinese-ideographs#153 (comment)

The PR is not closed automatically after pushing to main in the upstream repo. I suppose because the commit is changed.

I've changed the committer but I keep myself as the author. I think GitHub also changes the committer info when you "rebase and merge".

On the other hand, the commit appears as "partially verified" because it does not contain the author's signature. I think there is no way to add multiple GPG signatures to a git commit. I do not like to lose the original author's signature but the only alternative I see now is using a merge commit instead of rebasing. Anyway, I suppose the future merge script should check the original commit signature.

cc @da2ce7