Clean up and annotate release workflow

Author: jwpereira

.github/workflows/release.yml

@@ -13,48 +13,58 @@ jobs:
     name: Build
     runs-on: ubuntu-latest
     outputs:
-      tag: ${{ steps.release_info.outputs.tag }}
+      tag: ${{ steps.update-package-version.outputs.version }}
     steps:
+      # Configure runner with the right stuff
       - uses: actions/checkout@v2
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-
       - name: Configure git
         run: |
           git config user.name 'Release Action'
           git config user.email '<>'
-
       - uses: actions/setup-node@v1
         with:
           node-version: "12"
 
+      # Call `npm version`. It increments the version and commits the changes.
+      # We'll save the output (new version string) for use in the following
+      # steps
       - name: Update package version
         id: update-package-version
         run: |
           VERSION=$(npm version "${{ github.event.inputs.npm-version-arg }}")
           echo "::set-output name=version::$VERSION"
 
+      # Update the branch with the new commit
       - name: Push new version
         run: git push
 
+      # Now carry on, business as usual
       - name: Perform npm tasks
         run: npm run ci
 
+      # Finally, create a detached commit containing the built artifacts and tag
+      # it with the release. Note: the fact that the branch is locally updated
+      # will not be relayed (pushed) to origin
       - name: Commit to release branch
         id: release_info
         run: |
-          TAG="v${{ steps.update-package-version.outputs.version }}"
-          BRANCH="release/$TAG"
-          git switch -c $BRANCH
+          # Retrieve the previously created tag
+          TAG="${{ steps.update-package-version.outputs.version }}"
+
+          # Add the built artifacts. Using --force because dist/lib should be in
+          # .gitignore
           git add --force dist lib
 
+          # Make the commit
           MESSAGE="Build for $(git rev-parse --short HEAD)"
           git commit --allow-empty -m "$MESSAGE"
+
+          # Create an annotated tag and push it to origin
           git tag -a -m "Release $TAG" $TAG
           git push origin $TAG
 
-          echo "::set-output name=tag::$TAG"
-
   release:
     name: Release
     runs-on: ubuntu-latest