ci: Harmonise workflow description files

Make workflow description files more consistent:

- Add a comment to describe the workflow at the top of the file, for
  workflows that didn't have one yet
- Use consistent options for tmate options on "workflow_dispatch"
- Use a consistent order for trigger events ("on:")
- Use a consistent order for workflow permissions
- Use a blank line between top-level sections
- Remove trailing blank lines at the end of files

The objective is to make it easier to compare the different workflow
files visually.

No functional change.

Signed-off-by: Quentin Monnet <[email protected]>

.github/workflows/bump.yml

@@ -1,4 +1,8 @@
+# Check for Cargo dependencies updates, and automatically open a Pull Request
+# if updates are found.
+
 name: "bump.yml"
+
 on:
   workflow_dispatch:
     inputs:
@@ -19,9 +23,10 @@ concurrency:
 
 permissions:
   contents: "write"
-  pull-requests: "write"
   packages: "read"
   id-token: "write"
+  pull-requests: "write"
+
 jobs:
   update:
     runs-on: "ubuntu-latest"

.github/workflows/dev.yml

@@ -8,7 +8,9 @@
 # Production artifacts are produced in a sterile environment (in another CI workflow).
 
 name: "dev.yml"
+
 on:
+  push: {}
   merge_group:
   workflow_dispatch:
     inputs:
@@ -17,7 +19,6 @@ on:
         description: "Run with tmate enabled"
         required: false
         default: false
-  push: {}
 
 concurrency:
   group: "${{ github.workflow }}:${{ github.ref }}"
@@ -170,5 +171,3 @@ jobs:
         run: |
           >&2 echo "A critical step failed!"
           exit 1
-
-

.github/workflows/docs.yml

@@ -1,16 +1,22 @@
+# Build and deploy the dataplane design documentation.
+# Publish a new version of the docs for pushes to "main", or deploy a preview
+# when the workflow runs for a Pull Request.
+
 name: "docs.yml"
 
 on:
+  pull_request: {}
+  push:
+    branches:
+      - "main"
+  merge_group:
   workflow_dispatch:
     inputs:
       debug_enabled:
         type: "boolean"
-        description: "Run the build with tmate debugging enabled"
-  pull_request: { }
-  merge_group:
-  push:
-    branches:
-      - "main"
+        description: "Run with tmate enabled"
+        required: false
+        default: false
 
 concurrency:
   group: "${{ github.workflow }}:${{ github.event.pull_request.number || github.event.after }}"

.github/workflows/mergeability.yml

@@ -1,3 +1,5 @@
+# Block Pull Request merge (by failing the check) if specific labels are set.
+
 name: Mergeability
 
 on:

.github/workflows/sterile.yml

@@ -1,9 +1,11 @@
 # This is a sterile build and test workflow that uses the `dev-env` container image
 # to build and test the project in a sterile environment.
 # Artifacts produced by this workflow are intended to be used for production.
+
 name: "sterile.yml"
+
 on:
-  push:
+  push: {}
   merge_group:
   workflow_dispatch:
     inputs:
@@ -240,4 +242,3 @@ jobs:
         run: |
           >&2 echo "One or more required pushes failed"
           exit 1
-