Apply suggestions from code review

Co-authored-by: Marco Franssen <marco.franssen@philips.com>
Signed-off-by: Brend Smits <brend.smits@philips.com>

Makefile

@@ -87,13 +87,18 @@ release-vars: ## print the release variables for goreleaser
 
 .PHONY: gh-release
 gh-release: ## Creates a new release by creating a new tag and pushing it
-	git stash
-	sed -i 's/$(OLD_VERSION)/$(NEW_VERSION)/g' .github/workflows/*.yaml
-	sed -i 's/$(OLD_VERSION)/$(NEW_VERSION)/g' *.yaml *.md
-	git add .
-	git commit -s -m "$(DESCRIPTION)"
-	git tag -sam "$(DESCRIPTION)" $(NEW_VERSION)
-	git push $(NEW_VERSION)
-	@echo ATTENTION: MANUAL ACTION REQUIRED!! -- Wait for the release workflow to finish, then push the main branch using git push
-	git stash pop
+	@git stash -u
+	@echo Bumping $(OLD_VERSION) to $(NEW_VERSION)…
+	@sed -i 's/$(OLD_VERSION)/$(NEW_VERSION)/g' .github/workflows/*.yaml *.yaml *.md
+	@git add .
+	@git commit -s -m "Bump $(OLD_VERSION) to $(NEW_VERSION) for release"
+	@git tag -sam "$(DESCRIPTION)" $(NEW_VERSION)
+	@git push $(NEW_VERSION)
+	@echo ATTENTION: MANUAL ACTION REQUIRED!! -- Wait for the release workflow to finish
+	@echo
+	@echo Check status here https://github.com/philips-labs/slsa-provenance-action/actions/workflows/ci.yaml
+	@echo
+	@echo Once finished, push the main branch using 'git push'
+	@echo
+	@git stash pop
 

release.md

@@ -1,20 +1,31 @@
-# Automated release procedure
+# Release procedures
+
+## Automated release procedure
+
+To make a new release you can make use of the following `make` task.
 
-A make script has been created to automate the manual procedure.
-Execute the following command:
 ```bash
 make gh-release NEW_VERSION=v0.6.0 OLD_VERSION=v0.5.0 DESCRIPTION="A test release to see how it works"
 ```
 
-`NEW_VERSION` is the version that you want to release.
-`OLD_VERSION` is the previous version you wish to overwrite in the markdown and yaml files.
-`DESCRIPTION` is the description to use in the annotation of the tag and commit description.
+`NEW_VERSION` the version that you want to release.
+`OLD_VERSION` the current version you wish to replace in the markdown and yaml files.
+`DESCRIPTION` the annotation used when tagging the release.
+
+### ⚠ Important alert for MacOS users ⚠
+
+On MacOS `sed` has different behaviour and therefore doesn't work out of the box.
+A workaround to make it work is to install gnu-sed and alias it in your bashrc/zshrc:
 
-# Manual release procedure
+```bash
+brew install gnu-sed
+echo "alias sed=gsed" >> ~/.zshrc
+```
+
+## Manual release procedure
 
 1. Upgrade version number in all repository files, find & replace previous version number with new version number.
 1. Commit the changed files.
 1. Tag the new commit using `git tag -sam "What is this release about?" v0.1.0`.
 1. Push the tag to remote using `git push v0.1.0`
 1. Wait for the release workflow to finish, then push the main branch using `git push`
-