ci(github): extract Bash instructions in script files & improve the existing one

Djaytan commented 9 months ago

Note: the change has been tested successfully in the semantic-release-experiments repository: https://github.com/Djaytan/semantic-release-experiments/actions/runs/7943087923.

Google Shell Style Guide

This change rely on the Google Shell Style Guide which is available here: https://google.github.io/styleguide/shellguide.html

Most of the mentioned ones have been followed, especially these ones:

Commenting the scripts and functions.
Naming conventions for script files, functions and variables.
Variables scope reduction by relying on local keyword.
Favoring code execution inside main() functions instead of right into the script as is.
Making global variables readonly whenever relevant (always in our case).
Always printing error messages in stderr instead of stdout.
...

All the details are available in the Shell Style Guide provided above.

Signing logic extraction in separated Bash scripts

Extracting the whole signing logic into Bash scripts for the following reasons:

More portability across CI platforms. While the main script sign_gh_release_assets.sh remains tight to GitHub and the GitHub CLI, the core signing logic available in sigstore_file_signer.sh is a lot more agnostic and thus reusable in different contexts and CIs platforms (that's particularly important since these files are expected to be reused in other projects with potentially different requirements).
Testability improvement (mainly thanks to the possibility to test the signing logic in localdev)
Better rendering of the Bash scripts in editors with syntax highlighting, auto-completion, etc (IntelliJ IDEA, VSCode, ...) + Easier run ShellCheck & Shfmt tools over them

The idea of writing automated tests over the Bash scripts have been considered, and experimentation have been made with the ShellSpec tool. However, it was considered as too overkill for the few and pretty simple scripts that the project contains. Hence, the idea has been dropped to avoid unnecessary addition of complexity on the project.

Spigot plugin generation script adjustments

Printing back logs in stdout when executing the mvn versions:set commands for easier debugging in case of issue
Compliance with the Google Shell Style Guide