ci: adds lint check and fixes bad links and yaml formatting

.github/CONTRIBUTING.md

@@ -9,7 +9,7 @@ When submitting code, please apply [Square Code Style](https://github.com/square
 ## License
 
 By contributing your code, you agree to license your contribution under
-the terms of the [APLv2](LICENSE).
+the terms of the [APLv2](../LICENSE).
 
 All files are released with the Apache 2.0 license.
 

.github/workflows/create_release.yml

@@ -1,13 +1,12 @@
-# yamllint --format github .github/workflows/create_release.yml
 ---
 name: create_release
 
-# We create a release version on a trigger tag, regardless of if the commit is documentation-only.
-#
-# See https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
-on:
+# We create a release version on a trigger tag, regardless of if the commit is
+# documentation-only.
+on:  # yamllint disable-line rule:truthy
   push:
-    tags: 'release-[0-9]+.[0-9]+.[0-9]+**'  # Ex. release-1.2.3
+    tags:  # e.g. release-1.2.3
+      - 'release-[0-9]+.[0-9]+.[0-9]+**'
 
 jobs:
   create_release:
@@ -16,10 +15,10 @@ jobs:
       - name: Checkout Repository
         uses: actions/checkout@v4
         with:
-          # Prevent use of implicit GitHub Actions read-only token GITHUB_TOKEN. We don't deploy on
-          # the tag MAJOR.MINOR.PATCH event, but we still need to deploy the maven-release-plugin master commit.
+          # Prevent use of implicit GitHub Actions read-only GITHUB_TOKEN
+          # because maven-release-plugin pushes commits to master.
           token: ${{ secrets.GH_TOKEN }}
-          fetch-depth: 1  # only need the HEAD commit as license check isn't run
+          fetch-depth: 1  # license check is skipped, so we don't need history
       - name: Setup java
         uses: actions/setup-java@v4
         with:
@@ -36,9 +35,9 @@ jobs:
           # GH_USER=<user that created GH_TOKEN>
           GH_USER: ${{ secrets.GH_USER }}
           # GH_TOKEN=<hex token value>
-          #   - makes release commits and tags
-          #   - needs repo:status, public_repo
-          #   - referenced in .settings.xml
+          # * makes release commits and tags
+          # * needs repo:status, public_repo
+          # * referenced in .settings.xml
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
         run: |  # GITHUB_REF will be refs/tags/release-MAJOR.MINOR.PATCH
           build-bin/git/login_git &&

.github/workflows/deploy.yml

@@ -4,13 +4,14 @@ name: deploy
 
 # We deploy on master and release versions, regardless of if the commit is
 # documentation-only or not.
-#
-# See https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
-on:
+on:  # yamllint disable-line rule:truthy
   push:
-    # Don't deploy tags as they conflict with [maven-release-plugin] prepare release MAJOR.MINOR.PATCH
-    tags: ''
-    branches: master
+    branches:
+      - master
+    # Don't deploy tags because the same commit for MAJOR.MINOR.PATCH is also
+    # on master: Redundant deployment of a release version will fail uploading.
+    tags-ignore:
+      - '*'
 
 jobs:
   deploy:
@@ -19,10 +20,11 @@ jobs:
       - name: Checkout Repository
         uses: actions/checkout@v4
         with:
-          # Prevent use of implicit GitHub Actions read-only token GITHUB_TOKEN.
-          # We push Javadocs to the gh-pages branch on commit.
+          # Prevent use of implicit GitHub Actions read-only GITHUB_TOKEN
+          # because javadoc_to_gh_pages pushes commits to the gh-pages branch.
           token: ${{ secrets.GH_TOKEN }}
-          fetch-depth: 0  # allow build-bin/idl_to_gh_pages to get the full history
+          # allow build-bin/javadoc_to_gh_pages to get the full history
+          fetch-depth: 0
       - name: Setup java
         uses: actions/setup-java@v4
         with:
@@ -38,6 +40,7 @@ jobs:
         uses: actions/cache@v3
         with:
           path: ~/.npm
+          # yamllint disable-line rule:line-length
           key: ${{ runner.os }}-npm-packages-${{ hashFiles('zipkin-lens/package-lock.json') }}
       # Don't attempt to cache Docker. Sensitive information can be stolen
       # via forks, and login session ends up in ~/.docker. This is ok because
@@ -47,31 +50,30 @@ jobs:
           # GH_USER=<user that created GH_TOKEN>
           GH_USER: ${{ secrets.GH_USER }}
           # GH_TOKEN=<hex token value>
-          #   - pushes gh-pages during build-bin/javadoc_to_gh_pages
-          #   - pushes Docker images to ghcr.io
-          #   - create via https://github.com/settings/tokens
-          #   - needs repo:status, public_repo, write:packages, delete:packages
+          # * pushes gh-pages during build-bin/javadoc_to_gh_pages
+          # * pushes Docker images to ghcr.io
+          # * create via https://github.com/settings/tokens
+          # * needs repo:status, public_repo, write:packages, delete:packages
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           GPG_SIGNING_KEY: ${{ secrets.GPG_SIGNING_KEY }}
           # GPG_PASSPHRASE=<passphrase for GPG_SIGNING_KEY>
-          #   - referenced in .settings.xml
+          # * referenced in .settings.xml
           GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
           # SONATYPE_USER=<sonatype account token>
-          #   - deploys snapshots and releases to Sonatype
-          #   - needs access to io.zipkin via https://issues.sonatype.org/browse/OSSRH-16669
-          #   - generate via https://oss.sonatype.org/#profile;User%20Token
-          #   - referenced in .settings.xml
+          # * deploys snapshots and releases to Sonatype
+          # * needs access to io.zipkin via OSSRH-16669
+          # * generate via https://oss.sonatype.org/#profile;User%20Token
+          # * referenced in .settings.xml
           SONATYPE_USER: ${{ secrets.SONATYPE_USER }}
           # SONATYPE_PASSWORD=<password to sonatype account token>
-          #   - referenced in .settings.xml
+          #  * referenced in .settings.xml
           SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}
           # DOCKERHUB_USER=<typically dockerzipkindeployer>
-          #   - only push top-level projects: zipkin zipkin-aws zipkin-dependencies zipkin-gcp to Docker Hub, only on release
-          #   - login like this: echo "$DOCKERHUB_TOKEN"| docker login -u "$DOCKERHUB_USER" --password-stdin
+          #  * only push repos in openzipkin org to Docker Hub on release
           DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USER }}
           # DOCKERHUB_TOKEN=<access token for DOCKERHUB_USER>
-          #   -  Access Token from here https://hub.docker.com/settings/security
+          #  * Access Token from here https://hub.docker.com/settings/security
           DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
-        run: |  # GITHUB_REF will be refs/heads/master or refs/tags/MAJOR.MINOR.PATCH
+        run: |  # GITHUB_REF = refs/heads/master or refs/tags/MAJOR.MINOR.PATCH
           build-bin/configure_deploy &&
           build-bin/deploy $(echo ${GITHUB_REF} | cut -d/ -f 3)

.github/workflows/docker_push.yml

@@ -1,13 +1,12 @@
-# yamllint --format github .github/workflows/docker_push.yml
 ---
 name: docker_push
 
-# We re-push docker images on a trigger tag, regardless of if the commit is documentation-only.
-#
-# See https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
-on:
+# We re-push docker on a trigger tag, regardless of if the commit is
+# documentation-only.
+on:  # yamllint disable-line rule:truthy
   push:
-    tags: 'docker-[0-9]+.[0-9]+.[0-9]+**'  # Ex. docker-1.2.3
+    tags:  # e.g. release-1.2.3
+      - 'release-[0-9]+.[0-9]+.[0-9]+**'
 
 jobs:
   docker_push:
@@ -21,22 +20,21 @@ jobs:
       # via forks, and login session ends up in ~/.docker. This is ok because
       # we publish DOCKER_PARENT_IMAGE to ghcr.io, hence local to the runner.
       - name: Docker Push
-        run: |  # GITHUB_REF will be refs/tags/docker-MAJOR.MINOR.PATCH
+        run: |  # GITHUB_REF = refs/tags/docker-MAJOR.MINOR.PATCH
           build-bin/git/login_git &&
           build-bin/docker/configure_docker_push &&
           build-bin/docker_push $(echo ${GITHUB_REF} | cut -d/ -f 3)
         env:
           # GH_USER=<user that created GH_TOKEN>
           GH_USER: ${{ secrets.GH_USER }}
           # GH_TOKEN=<hex token value>
-          #   - pushes Docker images to ghcr.io
-          #   - create via https://github.com/settings/tokens
-          #   - needs repo:status, public_repo, write:packages, delete:packages
+          # * pushes Docker images to ghcr.io
+          # * create via https://github.com/settings/tokens
+          # * needs repo:status, public_repo, write:packages, delete:packages
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           # DOCKERHUB_USER=<typically dockerzipkindeployer>
-          #   - only push top-level projects: zipkin zipkin-aws zipkin-dependencies zipkin-gcp to Docker Hub, only on release
-          #   - login like this: echo "$DOCKERHUB_TOKEN"| docker login -u "$DOCKERHUB_USER" --password-stdin
+          #  * only push repos in openzipkin org to Docker Hub on release
           DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USER }}
           # DOCKERHUB_TOKEN=<access token for DOCKERHUB_USER>
-          #   -  Access Token from here https://hub.docker.com/settings/security
+          #  * Access Token from here https://hub.docker.com/settings/security
           DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}

.github/workflows/lint.yml

@@ -0,0 +1,36 @@
+---
+name: lint
+
+on:  # yamllint disable-line rule:truthy
+  push:  # non-tagged pushes to master
+    branches:
+      - master
+    tags-ignore:
+      - '*'
+    paths:
+      - '**/*.md'
+      - '.github/workflows/*.yml'
+      - './build-bin/*lint'
+      - ./build-bin/mlc_config.json
+  pull_request:  # pull requests targeted at the master branch.
+    branches:
+      - master
+    paths:
+      - '**/*.md'
+      - '.github/workflows/*.yml'
+      - './build-bin/*lint'
+      - ./build-bin/mlc_config.json
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-22.04  # newest available distribution, aka jellyfish
+    # skip commits made by the release plugin
+    if: "!contains(github.event.head_commit.message, 'maven-release-plugin')"
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+      - name: Lint
+        run: |
+          build-bin/configure_lint
+          build-bin/lint

.github/workflows/test.yml

@@ -1,63 +1,43 @@
-# yamllint --format github .github/workflows/test.yml
 ---
 name: test
 
 # We don't test documentation-only commits.
-on:
-  # We run tests on non-tagged pushes to master that aren't a commit made by the release plugin
-  push:
-    tags: ""
-    branches: master
+on:  # yamllint disable-line rule:truthy
+  push:  # non-tagged pushes to master
+    branches:
+      - master
+    tags-ignore:
+      - '*'
     paths-ignore:
-      - "**/*.md"
-      - "charts/**"
-  # We also run tests on pull requests targeted at the master branch.
-  pull_request:
-    branches: master
+      - '**/*.md'
+      - './build-bin/*lint'
+      - ./build-bin/mlc_config.json
+  pull_request:  # pull requests targeted at the master branch.
+    branches:
+      - master
     paths-ignore:
-      - "**/*.md"
-      - "charts/**"
+      - '**/*.md'
+      - './build-bin/*lint'
+      - ./build-bin/mlc_config.json
 
 jobs:
-  test-javadoc:
-    name: Test JavaDoc Builds
-    runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish
-    if: "!contains(github.event.head_commit.message, 'maven-release-plugin')"
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0 # full git history for license check
-      - name: Setup java
-        uses: actions/setup-java@v4
-        with:
-          distribution: 'zulu'  # zulu as it supports a wide version range
-          java-version: '17'  # earliest LTS supported by Spring Boot 3
-      - name: Cache local Maven repository
-        uses: actions/cache@v3
-        with:
-          path: ~/.m2/repository
-          key: ${{ runner.os }}-jdk-17-maven-${{ hashFiles('**/pom.xml') }}
-          restore-keys: ${{ runner.os }}-jdk-17-maven-
-      - name: Build JavaDoc
-        run: ./mvnw clean javadoc:aggregate -Prelease
-
   test:
     name: test (JDK ${{ matrix.java_version }})
-    runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish
+    runs-on: ubuntu-22.04  # newest available distribution, aka jellyfish
+    # skip commits made by the release plugin
     if: "!contains(github.event.head_commit.message, 'maven-release-plugin')"
     strategy:
-      fail-fast: false  # don't fail fast as sometimes failures are operating system specific
-      matrix:  # use latest available versions and be consistent on all workflows!
+      fail-fast: false  # don't fail fast as some failures are LTS specific
+      matrix:  # match with maven-enforcer-plugin rules in pom.xml
         include:
           - java_version: 17  # earliest LTS supported by Spring Boot 3
-            maven_args: -Prelease -Dgpg.skip -Dmaven.javadoc.skip=true
+            maven_args: -Prelease -Dgpg.skip
           - java_version: 21  # Most recent LTS
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0 # full git history for license check
+          fetch-depth: 0  # full git history for license check
       - name: Setup java
         uses: actions/setup-java@v4
         with:
@@ -67,18 +47,23 @@ jobs:
         uses: actions/cache@v3
         with:
           path: ~/.m2/repository
+          # yamllint disable-line rule:line-length
           key: ${{ runner.os }}-jdk-${{ matrix.java_version }}-maven-${{ hashFiles('**/pom.xml') }}
           restore-keys: ${{ runner.os }}-jdk-${{ matrix.java_version }}-maven-
       - name: Cache NPM Packages
         uses: actions/cache@v3
         with:
           path: ~/.npm
+          # yamllint disable-line rule:line-length
           key: ${{ runner.os }}-npm-packages-${{ hashFiles('zipkin-lens/package-lock.json') }}
       - name: Test without Docker
-        run: build-bin/maven_go_offline && build-bin/test -DexcludedGroups=docker ${{ matrix.maven_args }}
+        run: |
+          build-bin/maven_go_offline &&
+          build-bin/test -DexcludedGroups=docker ${{ matrix.maven_args }}
 
   test_docker:
-    runs-on: ubuntu-22.04 # newest available distribution, aka jellyfish
+    runs-on: ubuntu-22.04  # newest available distribution, aka jellyfish
+    # skip commits made by the release plugin
     if: "!contains(github.event.head_commit.message, 'maven-release-plugin')"
     strategy:
       matrix:
@@ -94,7 +79,7 @@ jobs:
       - name: Checkout Repository
         uses: actions/checkout@v4
         with:
-          fetch-depth: 1 # -Dlicense.skip=true so we don't need a full clone
+          fetch-depth: 1  # -Dlicense.skip=true, so we don't need a full clone
       - name: Setup java
         uses: actions/setup-java@v4
         with:
@@ -104,6 +89,7 @@ jobs:
         uses: actions/cache@v3
         with:
           path: ~/.m2/repository
+          # yamllint disable-line rule:line-length
           key: ${{ runner.os }}-jdk-${{ matrix.java_version }}-maven-${{ hashFiles('**/pom.xml') }}
           restore-keys: ${{ runner.os }}-jdk-${{ matrix.java_version }}-maven-
       # Don't attempt to cache Docker. Sensitive information can be stolen
@@ -118,5 +104,8 @@ jobs:
         run: |
           build-bin/docker/configure_docker &&
           build-bin/maven/maven_go_offline &&
-          MAVEN_GOAL=install build-bin/maven/maven_build -pl :${{ matrix.name }} --am &&
-          build-bin/test -Dgroups=docker -pl :${{ matrix.name }} -Dlicense.skip=true
+          build-bin/maven/maven_build -pl :${{ matrix.name }} --am &&
+          build-bin/test -Dgroups=docker -pl :${{ matrix.name }}
+        env:
+          MAVEN_GOAL: install  # docker build needs dependencies in mavenLocal
+          MAVEN_CONFIG: '-Dlicense.skip=true'  # license check already run