Release tag mechanism for locked-down installs

Push a labeled version of crucible that passes ci after merging,
including all pinned commits of the sub-projects. This release
mechanism will be used for regression testing and also by users
that need more determinsm from crucible stable installs that do
not change over time.

The mechanism includes a scheduled job that runs periodically
and also by manual trigger with custom params.

Additional changes are required to implement the installation
bits that will take advantage of this release tag mechanism.
This install feature will be implemented after the release
mechanism.

.github/workflows/crucible-release.yaml

@@ -0,0 +1,203 @@
+name: crucible-release
+on:
+  schedule:
+    # Runs every 3 months (1st day of the quarter)
+    - cron: "0 0 1 */3 *"
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        required: false
+        type: boolean
+        description: Do NOT push/delete tag to/from the repositories
+        default: false
+    inputs:
+      custom-tag:
+        required: false
+        type: string
+        description: Custom tag to push/delete
+      action:
+        required: true
+        type: choice
+        options:
+        - push
+        - delete
+        description: Action to perform with the custom-tag (push or delete)
+        default: push
+
+jobs:
+  release-tag:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      tag: ${{ steps.gen-release-tag.outputs.tag }}
+    steps:
+    - name: Generate release tag
+      if: github.event_name != 'workflow_dispatch' || github.event.inputs.custom_tag == ''
+      id: gen-release-tag
+      run: |
+          year="$(date +%Y)"
+          month="$(date +%m)"
+          quarter="$(((month-1)/3+1))"
+          echo "tag=$year.$quarter" >> $GITHUB_OUTPUT
+    - name: Generate custom tag
+      if: github.event_name == 'workflow_dispatch' && github.event.inputs.custom_tag != ''
+      id: gen-custom-tag
+      env:
+          CUSTOM_TAG: ${{ inputs.custom-tag }}
+      run: |
+          echo "tag=$CUSTOM_TAG" >> $GITHUB_OUTPUT
+    - name: Get release tag
+      id: get-release-tag
+      env:
+          TAG: ${{ needs.release-tag.outputs.tag }}
+      run: echo "$TAG"
+
+  crucible-tag:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    - name: checkout crucible default
+      uses: actions/checkout@v4
+      with:
+        repository: perftool-incubator/crucible
+        ref: master
+        path: crucible
+    - name: get tags from the crucible repo
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd crucible
+          git ls-remote --tags origin
+    - name: push if tag does not exist in the crucible repo
+      if: ${{ inputs.dry_run == false && inputs.action != 'delete' }}
+      env:
+        TAG: ${{ needs.release-tag.outputs.tag }}
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd crucible
+          git ls-remote --tags origin | grep -v "$TAG" && \
+          git tag $TAG && git push origin $TAG
+    - name: check if tag has been pushed
+      if: ${{ inputs.dry_run == false && inputs.action == 'push' }}
+      env:
+        TAG: ${{ needs.release-tag.outputs.tag }}
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd crucible
+          git ls-remote --tags origin | grep "$TAG"
+          git fetch -t
+          git tag -l "$TAG"
+    - name: delete if action==delete and tag exists in the crucible repo
+      if: ${{ inputs.dry_run == false && inputs.action == 'delete' }}
+      env:
+        TAG: ${{ needs.release-tag.outputs.tag }}
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd crucible
+          git ls-remote --tags origin | grep "$TAG" && \
+          git push --delete origin $TAG
+    - name: check if tag has been deleted
+      if: ${{ inputs.dry_run == false && inputs.action == 'delete' }}
+      env:
+        TAG: ${{ needs.release-tag.outputs.tag }}
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd crucible
+          git ls-remote --tags origin | grep -v "$TAG"
+
+  get-sub-projects:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      repos: ${{ steps.get-repos.outputs.repos }}
+    steps:
+    - name: Get the list of sub-projects
+      id: get-repos
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd crucible
+          # get first column (repo name) and add to a bash array ( a b c)
+          projects=( $(grep -v ^# config/default_subprojects | awk {'print $1'} ) )
+          # builtin implict join array a,b,c
+          printf -v list '%s,' "${projects[@]}"
+          # convert to a comma separated list [a,b,c]
+          echo "repos=[${list%,}]" >> $GITHUB_OUTPUT
+    - name: Get the sub-projects list
+      id: get-projects-list
+      env:
+          REPOS: ${{ needs.get-repos.outputs.repos }}
+      run: echo "$REPOS"
+
+  projects-tag:
+    needs:
+    - get-sub-projects
+    strategy:
+        matrix:
+            repository: ${{ needs.get-sub-projects.outputs.repos }}
+    steps:
+    - name: Display sub-project repository name
+      run: |
+          echo "repository=${{ matrix.repository }}"
+    - name: checkout sub-project repository
+      uses: actions/checkout@v4
+      with:
+        repository: perftool-incubator/${{ matrix.repository }}
+        ref: ''
+        path: ''
+    - name: get remote tags
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd ${{ matrix.repository }}
+          git ls-remote --tags origin
+    - name: create release tag
+      env:
+        TAG: ${{ needs.release-tag.outputs.tag }}
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd ${{ matrix.repository }}
+          git tag $TAG
+    - name: push release tag
+      if: ${{ inputs.dry_run == false && inputs.action == 'push' }}
+      env:
+        TAG: ${{ needs.release-tag.outputs.tag }}
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd ${{ matrix.repository }}
+          git ls-remote --tags origin | grep -v "$TAG" && \
+          git tag $TAG && git push origin $TAG
+    - name: check if tag has been pushed
+      if: ${{ inputs.dry_run == false && inputs.action == 'push' }}
+      env:
+        TAG: ${{ needs.release-tag.outputs.tag }}
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd ${{ matrix.repository }}
+          git ls-remote --tags origin | grep "$TAG"
+          git fetch -t
+          git tag -l "$TAG"
+    - name: delete if action==delete and tag exists in the project repo
+      if: ${{ inputs.dry_run == false && inputs.action == 'delete' }}
+      env:
+        TAG: ${{ needs.release-tag.outputs.tag }}
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd ${{ matrix.repository }}
+          git ls-remote --tags origin | grep "$TAG" && \
+          git push --delete origin $TAG
+    - name: check if tag has been deleted
+      if: ${{ inputs.dry_run == false && inputs.action == 'delete' }}
+      env:
+        TAG: ${{ needs.release-tag.outputs.tag }}
+      run: |
+          cd $GITHUB_WORKSPACE
+          cd crucible
+          git ls-remote --tags origin | grep -v "$TAG"
+
+  crucible-release-complete:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    needs:
+    - release-tag
+    - crucible-tag
+    - projects-tag
+    steps:
+    - name: Confirm Success
+      run: echo "crucible-release-complete"

spec/release-tag.md

@@ -0,0 +1,69 @@
+# Release tag
+Implement a "Release" mechanism for installing "consistent" versions of
+Crucible.
+
+## Problem description
+We need to be able to install a "version" of Crucible that is "locked down"
+and won't change at all if it is installed over time.
+
+Crucible installations cannot be used for regression testing in a consistent
+manner.
+
+bin/update will override the installed repository by pulling the latest commit
+if the installed commit is an older one.
+
+Crucible installer clones Crucible repository and all sub-projects from the
+latest "main" branch. A default installation contains all the Crucible
+repositories from the latest merged commits.
+
+```
+#project-name        project-type   git-repo-url                     branch
+rickshaw             core           /rickshaw                        master
+multiplex            core           /multiplex                       master
+roadblock            core           /roadblock                       master
+...
+hwlatdetect          benchmark      /bench-hwlatdetect               main
+tracer               benchmark      /bench-tracer                    main
+...
+ftrace               tool           /tool-ftrace                     master
+testing              doc            /testing-repo                    master
+...
+```
+
+## Proposed change
+"Locked down" release by pinning all sub-projects to a commit that is
+verified by CI after code merges. Sub-projects includes core and benchmark
+repositories. Stable releases must be labeled to be a "locked-down" version
+of Crucible installation.
+
+### Tagging
+The solution proposed consists in tagging specific commits of crucible
+and its sub-projects to label versions of Crucible that are verified.
+
+The tag format should be as follows:
+YYYY	4-digit Year
+N	Quarter (1=Jan-Mar, 2=Apr-Jun, 3=Jul-Sept, 4=Oct-Dec)
+
+Example: 2024.1, 2025.3
+
+### Scheduled job
+Create a new CI job that runs every quarter (scheduled) against merged
+commits that passed pre-merge jobs.
+
+The "crucible-release" job should check for the tag YYYY.N, and tag
+every repository, including the main Crucible project if the tag does
+NOT exist.
+
+The workflow_dispatch (manual trigger) job includes the following inputs:
+ - A `dry-run` mode will skip the push tag step for debugging purposes.
+ - A `custom-tag` for pushing/deleting an user-defined version label.
+ - An `action` choice to push or delete a tag
+
+### Installer
+- Add a new `--release=<tag>` to the installation to specify the release
+that will be installed.
+*TBD*
+
+### Crucible command
+- Add a new `crucible repo release` to list tagged releases
+*TBD*