ci: add job step names, workflow comments, and whitespace

Fdawgs · Mar 15, 2022 · 970f4db · 970f4db
1 parent ac15f3b
commit 970f4db
Show file tree

Hide file tree

Showing 5 changed files with 69 additions and 23 deletions.
diff --git a/.github/workflows/automerge.yml b/.github/workflows/automerge.yml
@@ -1,5 +1,8 @@
 name: Automerge Dependabot PRs
 
+# **What it does**: Automatically merge Dependabot PRs that pass the CI workflow run.
+# **Why we have it**: To keep our dependencies up-to-date, to avoid security issues.
+
 on:
     workflow_run:
         workflows: ["CI"]
@@ -13,7 +16,7 @@ jobs:
             github.actor == 'dependabot[bot]'
         runs-on: ubuntu-latest
         steps:
-            - name: Download Artifact
+            - name: Download artifact
               uses: actions/github-script@v6
               with:
                   script: |
@@ -36,7 +39,10 @@ jobs:
                       });
 
                       fs.writeFileSync('${{github.workspace}}/pr.zip', Buffer.from(download.data));
-            - run: unzip pr.zip
+
+            - name: Unzip artifact
+              run: unzip pr.zip
+
             - name: Comment on PR
               uses: actions/github-script@v6
               with:

diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
@@ -1,5 +1,8 @@
 name: CD
 
+# **What it does**: Automatically generates releases and release notes.
+# **Why we have it**: Allows development to focus on higher value work.
+
 on:
     push:
         branches:
@@ -20,20 +23,22 @@ jobs:
                   release-type: node
                   package-name: fastify-floc-off
 
-            - uses: actions/checkout@v2
+            - name: Check out repo
               if: steps.release.outputs.release_created
+              uses: actions/checkout@v2
 
-            - uses: actions/setup-node@v3
+            - name: Setup Node
+              if: steps.release.outputs.release_created
+              uses: actions/setup-node@v3
               with:
                   node-version: 16
                   registry-url: https://registry.npmjs.org/
-              if: steps.release.outputs.release_created
 
             - name: Publish to NPM
               if: steps.release.outputs.release_created
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
               # Disable Husky prepare script
               run: |
                   npm set-script prepare ""
                   npm publish --ignore-scripts
-              env:
-                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,5 +1,8 @@
 name: CI
 
+# **What it does**: Runs our tests.
+# **Why we have it**: We want our tests to pass before merging code.
+
 on:
     push:
         branches:
@@ -33,16 +36,23 @@ jobs:
         if: github.event.pull_request.draft == false
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
-            - uses: actions/setup-node@v3
+            - name: Check out repo
+              uses: actions/checkout@v2
+
+            - name: Setup Node
+              uses: actions/setup-node@v3
               with:
                   node-version: 16
+
             - name: Install
               run: npm install --ignore-scripts
+
             - name: Run ESLint
               run: npm run lint
+
             - name: Run Prettier
               run: npm run lint:prettier:ci
+
             - name: Run License Checker
               run: npm run lint:licenses
 
@@ -53,10 +63,13 @@ jobs:
             github.actor != 'dependabot[bot]'
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
+            - name: Check out repo
+              uses: actions/checkout@v2
               with:
                   fetch-depth: 0
-            - uses: wagoid/commitlint-github-action@v4
+
+            - name: Run Commitlint
+              uses: wagoid/commitlint-github-action@v4
               with:
                   configFile: ./package.json
 
@@ -69,16 +82,21 @@ jobs:
                 os: [macos-latest, ubuntu-latest, windows-latest]
         runs-on: ${{ matrix.os }}
         steps:
-            - uses: actions/checkout@v2
-            - name: Use Node.js ${{ matrix.node }}
+            - name: Check out repo
+              uses: actions/checkout@v2
+
+            - name: Setup Node ${{ matrix.node }}
               uses: actions/setup-node@v3
               with:
                   node-version: ${{ matrix.node }}
+
             - name: Install
               run: npm install --ignore-scripts
-            - name: Run Tests
+
+            - name: Run tests
               run: npm run jest:coverage
-            - name: Coveralls Parallel
+
+            - name: Coveralls parallel
               if: github.repository == 'Fdawgs/fastify-floc-off'
               uses: coverallsapp/github-action@1.1.3
               with:
@@ -94,7 +112,7 @@ jobs:
             github.repository == 'Fdawgs/fastify-floc-off'
         runs-on: ubuntu-latest
         steps:
-            - name: Coveralls Finished
+            - name: Coveralls finished
               uses: coverallsapp/github-action@1.1.3
               with:
                   github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -108,12 +126,16 @@ jobs:
             github.event_name == 'pull_request'
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
-            - name: Save PR Number
+            - name: Check out repo
+              uses: actions/checkout@v3
+
+            - name: Save PR number
               run: |
                   mkdir -p ./pr
                   echo ${{ github.event.number }} > ./pr/NR
-            - uses: actions/upload-artifact@v2
+
+            - name: Upload PR number in artifact
+              uses: actions/upload-artifact@v2
               with:
                   name: pr
                   path: pr/
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
@@ -1,5 +1,8 @@
 name: CodeQL Analysis
 
+# **What it does**: This runs CodeQL on this repo.
+# **Why we have it**: Security scanning.
+
 on:
     push:
         branches:
@@ -20,15 +23,18 @@ jobs:
         if: github.event.pull_request.draft == false
         runs-on: ubuntu-latest
         steps:
-            - name: Checkout Repository
+            - name: Check out repo
               uses: actions/checkout@v2
+
             # Initialises the CodeQL tools for scanning
             - name: Initialise CodeQL
               uses: github/codeql-action/init@v1
               with:
                   languages: javascript
                   queries: security-and-quality
+
             - name: Autobuild
               uses: github/codeql-action/autobuild@v1
-            - name: Perform CodeQL Analysis
+
+            - name: Perform CodeQL analysis
               uses: github/codeql-action/analyze@v1
diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml
@@ -1,5 +1,8 @@
 name: Check Markdown for Broken Links
 
+# **What it does**: Checks all links in markdown files, apart from links to repo commits and issues.
+# **Why we have it**: We want to know if any links break.
+
 on:
     push:
         branches:
@@ -32,9 +35,13 @@ jobs:
         if: github.event.pull_request.draft == false
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v2
-            - uses: actions/setup-node@v3
+            - name: Check out repo
+              uses: actions/checkout@v2
+
+            - name: Setup Node
+              uses: actions/setup-node@v3
               with:
                   node-version: 16
+
             - name: Run Linkinator
               run: npx linkinator '{,!(node_modules)/**/}*.md' --skip 'https:\/\/(?:www\.|)github\.com\/Fdawgs\/.*\/(?:commit|issues)\/, http://0.0.0.0'