Add build & release pipeline for versioned images

[snyssen]

Hi!

Following my issue (#94), here is the PR for the new workflow for automated release management and versioned images. I have refactored what I initially proposed from my blog (will have to update the post now 😁), but it still offers the same functionalities. Now, there are a few things you should know before you actually merge this PR and use the new workflow:

• As you already now, for the changelog to be correctly generated and the version number incremented, your commits have to follow the conventional commits convention. You will find a great (imho) cheat sheet here to quickly get you started. Also note that failing to respect the convention won't fail the pipeline, it just means the changelog and version number won't be updated correctly, so no biggie if that happens 😄 Finally, don't forget that this convention is only really needed on the main branch, and you can easily change the merge commit message when merging PR, so it's not a problem if you or other contributors do not respect the convention on other branches. It is however recommended to use squash-merge when merging PR.
• This workflow runs on every commit of every branch as well as on PRs, and will create new image tags for each of those run according to the following rules:
  • on commits in a branch: tag <branch_name> is pushed (e.g. commits on main branch create image bellamy/wallos:main
  • on opened PR: tag pr-<id> is created but not pushed (basically only checks that image is buildable) (e.g. pull request Adding input validation before saving to the db #105 creates image bellamy/wallos:pr-105)
  • on release PR merge (more on that later): tags <major>.<minor>.<patch>, <major>.<minor>, <major> and latest are pushed (e.g. merge of release PR 1.2.3 creates images bellamy/wallos:1.2.3, bellamy/wallos:1.2, bellamy/wallos:1 and bellamy/wallos:latest)
• The release system works with release PRs: when release-please detects changes between the latest release and the latest commits (by reading the commits in between and parsing them as conventional commits), it will open a pull request with an updated changelog and version, similar to this one. Merging the PR will create a new release with the appropriate changelog and version, and push a new image with the required version. This way, releases are created at your pace, when you feel like it.
• As you can see from the PR linked above, the initial release is expected to be version 1.0.0. This can be overriden by creating a commit (which can be empty), with the following commit body: Release-As: x.x.x. This behavior is documented here.
• There are a few parameters that can be changed in the env section of the workflow, mainly the target registry (currently docker.io) and credentials for it (currently depends on secrets that I am guessing were already created for the previous workflow?) and the project type (currently set to simple, so new releases only updates the changelog in the repo)

I realize this is a lot of information so it might seem scary, but I just want to give you the full guide, even though the actual use should be mostly automated and worry free 🙂 And if you have any question or remarks, please contact me back and I will be happy to help.

[ellite]

This is looking incredible. Thanks.
Does it build and push amd64, arm64 and arm/v7 images?

[snyssen]

Not in its current form, but I will see if I can make this work and update this PR!

[snyssen]

There, it should build for the required platforms now 😄 I also realized that I was previously targeting the wrong image name; it should be correct now

[ellite]

Thank you very much.

And now, to make sure my very tired brain is understanding all this.

So, In this scenario,

Current version is 1.2.3
I have a release with the following changes:

- New feature: Added ability to serve coffee
- Fixed: Fixed a typo on Italian translation
- Changed: Red save button is now green.

What should the branch name be like?
What should the merge message look like?

Appreciate your time and patience.

[snyssen]

You should ideally try to have a linear git history by using squash-merge, but it's simply because it makes the history easier to follow. Here is the workflow I would recommend when doing any work that could span more than a single commit:

1. Create a branch from main in which you will work. The branch name does not matter and could follow any convention or none at all. For external contributors, a fork counts as a new branch.
2. Do your work in that branch. I would suggest following the conventional commits convention for every commit, simply to force you to think about it; but you could use any kind of commit messages at this point, it should not matter until the branch is merged.
3. Once you are ready to put your work into the main branch (e.g. when you consider a new feature ready, or a bug fixed), open a pull request from your work branch to the main branch. The pull request has two advantages:
   • it triggers a new build, so you can be sure the software still compiles (and you could add another pipeline for actually running tests)
   • it allows you to easily do a squash-merge and update the merge commit to accurately represent your work in a single conventional commit. This conventional commit will later serve as an entry in your changelog when you decide to release a new version.

To do a squash-merge from an open pull request, simply select the squash and merge strategy in the merge form:

and then update the commit as needed (so this is the part where you should make sure to respect the conventional commits conventions):

When you accumulate enough work items following the guidelines above, simply merge the release PR that will have been automatically created by release-please to push a new release with all of those changes included.

---

If that is still unclear for you, let me show you a concrete example on one of my project. The latest release for that project is V2.2.5, which is a few months old already. Since I have had a few works done since that release (there were only dependencies updates, but the principles stay the same), there have been a few conventional commits following the release tag (which were all created by merging pull requests using squash-merge):

The new commits were automatically detected by release-please thanks to the Github Actions workflow we set up, so release-please created a release pull request for us:

Right now, I have a new pull request open (for yet another deps update haha). When I will merge it, it will create a new commit in the main branch, which will be detected by release-please, which will update the release pull request, adding a new line to the changelog. Finally, I will merge said release pull request, which will create the V2.2.6 release (since there are only fixes; if a commit with a new feature was present in the git history, the version would get bumped to v2.3.0 instead), creating a new commit similar to the one of release V2.2.5.

[snyssen]

Okay that was a lot, sorry... Let me just answer your two questions directly:

• The branch name does not matter
• The commits you listed should be:
  • feat: add ability to serve coffee
  • fix: fix a typo on Italian translation
  • feat: changed red save button to green
• The commit from the release pull request merge should not be changed from its automatically created message (something like chore(main): release 1.3.0 (#<pr-id>))

[ellite]

No no. Not too much. Very valuable explanation.
Thank you so much 🙏🙏

[ellite]

🙌

[snyssen]

I see the pipeline failed because release-please was not authorized to create its PR. I think you have to update your repo settings to authorize it. Go in settings/actions

then give read and write permissions and allow creating pull requests

then restart the failed job, and I think it should work 😄

[ellite]

Thanks. I added those permissions but it failed again.

Where are this coming from?

          registry: ${{ env.REGISTRY }}
          username: ${{ env.REGISTRY_USERNAME }}
          password: ${{ env.REGISTRY_PASSWORD }}

[snyssen]

Okay I think it might be due to the fact that the pipeline is running with my privileges (since those changes were made by me, and run from a PR initiated by me), so I am thinking of making a change to the pipeline so it doesn't run release Please on PR not on branches other than main (as it does not really make sense to run it in those contexte anyway). I'll update you after work, when I have access to my personal computer.

Where are this coming from?

          registry: ${{ env.REGISTRY }}
          username: ${{ env.REGISTRY_USERNAME }}
          password: ${{ env.REGISTRY_PASSWORD }}

These come from the env block, near the top of the pipeline file

[ellite]

Appreciate it 👍

[ellite]

Thank you very much again 🥇