Clarify release readme that refers to badges (#3545)

Also:
1. Point Renovate PR which updates the earthly version in our docs to
target `docs-0.7` branch
2. Add the Github workflow that was previously added to the docs-0.7 (to
avoid future potential merge conflicts)

.github/renovate.json5

@@ -4,6 +4,7 @@
     'config:recommended',
     'default:pinDigestsDisabled',
   ],
+  baseBranches: ['main', 'docs-0.7'],
   configMigration: true,
   prHourlyLimit: 1,
   prConcurrentLimit: 3,
@@ -49,6 +50,20 @@
       addLabels: [
         'earthly-version-in-docs',
       ],
+      automerge: true,
+    },
+    // Point earthly/earthly updates in docs to docs-0.7 branch by:
+    // 1. disable all PRs targeting docs-0.7 for all packages except earthly/earthly
+    {
+      baseBranchList: ['docs-0.7'],
+      excludePackagePatterns: ['earthly/earthly'],
+      enabled: false,
+    },
+    // 2. disable PRs targeting main for earthly/earthly
+    {
+      baseBranchList: ['main'],
+      matchPackagePatterns: ['earthly/earthly'],
+      enabled: false,
     },
   ],
 }

.github/workflows/docs-checks-links.yml

@@ -1,20 +1,38 @@
-name: check docs broken links
+name: Check Docs for Broken Links
 
 on:
-  push: # this can be removed if we noticed the workflow_run trigger is working as expected (after the gitbook workflow completes)
+  push:
     branches: [docs-0.7]
-  workflow_run:
-    workflows: ['GitBook']
-    types: [completed]
+  pull_request:
     branches: [docs-0.7]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
 jobs:
-  check-broken-links:
-    if: ${{ github.event_name == 'push' || github.event.workflow_run.conclusion == 'success' }}
+  check-broken-links-pr:
+    if: ${{ github.event_name == 'pull_request' }}
+    runs-on: "ubuntu-latest"
+    env:
+      FORCE_COLOR: 1
+      EARTHLY_TOKEN: "${{ secrets.EARTHLY_TOKEN }}"
+      EARTHLY_INSTALL_ID: "earthly-githubactions"
+      DOCKERHUB_MIRROR_USERNAME: "${{ secrets.DOCKERHUB_MIRROR_USERNAME }}"
+      DOCKERHUB_MIRROR_PASSWORD: "${{ secrets.DOCKERHUB_MIRROR_PASSWORD }}"
+      # Used in our github action as the token - TODO: look to change it into an input
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ref: ${{ github.head_ref }}
+      - uses: earthly/actions-setup@main
+      - name: Check Broken Links
+        run: earthly --ci +check-broken-links-pr --VERBOSE=true
+
+  check-broken-links-branch:
+    if: ${{ github.event_name == 'push' }}
     runs-on: "ubuntu-latest"
     env:
       FORCE_COLOR: 1

.github/workflows/release-merge-docs.yml

@@ -1,4 +1,4 @@
-name: update docs
+name: Merge main to docs-0.7 on New Earthly Release
 
 on:
   push:
@@ -11,7 +11,7 @@ concurrency:
 
 jobs:
   main-to-docs:
-    name: merge (dry-run)
+    name: merge main to docs-0.7
     runs-on: "ubuntu-latest"
     env:
       FORCE_COLOR: 1

release/README.md

@@ -30,13 +30,13 @@
   cd release
   env -i HOME="$HOME" PATH="$PATH" SSH_AUTH_SOCK="$SSH_AUTH_SOCK" RELEASE_TAG="$RELEASE_TAG" USER="$USER" PRERELEASE="$PRERELEASE" ./release.sh
   ```
-* Make sure `main` branch is properly merged to `docs-0.7`:
-  [![update docs](https://github.com/earthly/earthly/actions/workflows/release-merge-docs.yml/badge.svg)](https://github.com/earthly/earthly/actions/workflows/release-merge-docs.yml)
-
+* Wait for the [Merge main to docs-0.7 on New Earthly Release](../.github/workflows/release-merge-docs.yml) workflow to complete; this workflow automatically merges `main` into `docs-0.7`. You can watch for it here: [![Merge main to docs-0.7 on New Earthly Release](https://github.com/earthly/earthly/actions/workflows/release-merge-docs.yml/badge.svg)](https://github.com/earthly/earthly/actions/workflows/release-merge-docs.yml)  
+In case the workflow fails the manual process is:
+  ```shell
+    git checkout docs-0.7 && git pull && git merge main && git push
+    ```
 * Updating the Earthly version in our docs:
-  [Renovate](https://www.mend.io/renovate/) will open a PR to update all docs as soon as a new release is available in this repo,
-  which you should then review & merge (An example PR can be found [here](https://github.com/earthly/earthly/pull/3285/files)).
-* Commit updated version changes to `docs-0.7`.
+  [Renovate](https://www.mend.io/renovate/) will open a PR targeting `docs-0.7` branch to update all docs as soon as a new release is available in this repo which you should then review & merge (An example PR can be found [here](https://github.com/earthly/earthly/pull/3285/files)).
 * Merge `docs-0.7` into `main`.
   ```shell
     git checkout main && git merge docs-0.7 && git push
@@ -48,8 +48,7 @@
     `git checkout main && git push`
 
 <!-- vale HouseStyle.Spelling = YES -->
-* Make sure there are no broken links in https://docs.earthly.dev:
-  [![check docs broken links](https://github.com/earthly/earthly/actions/workflows/docs-checks-links.yml/badge.svg)](https://github.com/earthly/earthly/actions/workflows/docs-checks-links.yml)
+* Wait for the [Check Docs for Broken Links](../.github/workflows/docs-checks-links.yml) workflow to complete; this workflow validates https://docs.earthly.dev does not contain any broken links. You can watch for it here: [![Check Docs for Broken Links](https://github.com/earthly/earthly/actions/workflows/docs-checks-links.yml/badge.svg?event=push)](https://github.com/earthly/earthly/actions/workflows/docs-checks-links.yml)
 * Verify the [Homebrew release job](https://github.com/earthly/homebrew-earthly) has successfully run and has merged the new `release-v...` branch into `main`.
 * Copy the release notes you have written before and paste them in the Earthly Community slack channel `#announcements`, together with a link to the release's GitHub page. If you have Slack markdown editing activated, you can copy the markdown version of the text.
 
@@ -116,29 +115,7 @@ We currently have syntax highlighting for the following:
 
 #### VSCode + Github
 
-1. Go to the [repo](https://github.com/earthly/earthfile-grammar)
-1. Make relevant changes + test
-1. Set the version to publish:
-    ```bash
-    export VSCODE_RELEASE_TAG=${NEW_VERSION_HERE}
-    ```
-    
-    You can [see what is already published](https://marketplace.visualstudio.com/items?itemName=earthly.earthfile-syntax-highlighting)
-1. Make sure that the version has release notes already in the [README](https://github.com/earthly/earthfile-grammar/CHANGELOG.md)
-1. 
-    ```bash
-    earthly --release \
-      --build-arg VSCODE_RELEASE_TAG=${VSCODE_RELEASE_TAG}
-    ```
-1. Finally, tag git for future reference
-    ```bash
-    git tag "vscode-syntax-highlighting-$VSCODE_RELEASE_TAG"
-    git push origin "vscode-syntax-highlighting-$VSCODE_RELEASE_TAG"
-    ```
-
-- If `VSCE_TOKEN` token has expired, Vlad can regenerate one following [this guide](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#get-a-personal-access-token) and then setting it using `./earthly secrets set /earthly-technologies/vsce/token '...'`
-
-- If `OVSX_TOKEN` token has expired, Nacho can regenerate one following [this guide](https://github.com/eclipse/openvsx/wiki/Publishing-Extensions#3-create-an-access-token) and then setting it using `./earthly secrets set /earthly-technologies/ovsx/token '...'`
+Release instructions can be found in the [project repo](https://github.com/earthly/earthfile-grammar#how-to-release).
 
 #### Intellij