[WORKFLOW] Fix: enhance the timestamp exception to accommodate pure d…

…ocumentation PR's (#543)

* Skip timestamp check entirely when the last non-doc commit is already in main branch

* Update formatting; highlight importance of using merged branch

* MICROSOFT AUTOMATED PIPELINE: Stamp 'cwhitehead-msft-pr-doc-ignore-fix' with updated timestamp and hash after successful run

.github/workflow_metadata/README.md

@@ -3,20 +3,20 @@ Files in this directory are used to support workflow checks that run on the cali
 pr\_\* objects are used to validate a Pull Request run. This is in support of an honor based system that allows contributors to create internal pipelines (for example, to run tests with proprietary toolchains). The suggested procedure here is:
   1. Contributor develops a new feature and pushes a branch to the caliptra-rtl GitHub repository
   1. Contributor runs an internal workflow on a branch that contains the merge of the feature branch into main. This workflow includes the complete test-suite and (possibly) some additional checks required by the company policy of that contributor
-    - All contributors MUST perform the following checks in their development pipeline:
-      - VCS test of the complete L0 regression suite (smoke tests)
-      - Lint check run against caliptra_top
+      - All contributors MUST perform the following checks in their development pipeline:
+        - VCS test of the complete L0 regression suite (smoke tests)
+        - Lint check run against caliptra_top
   1. Upon successfully completing, the internal workflow runs the script [stamp_repo.sh](../scripts/stamp_repo.sh). This script:
-    - Updates the pr\_timestamp file to the current date
-    - Runs the hash script [file_hash.sh](../scripts/file_hash.sh) to measure the code that the workflow ran on (including the pr\_timestamp file)
-    - Writes the hash to the pr\_hash file
+      - Updates the pr\_timestamp file to the current date
+      - Runs the hash script [file_hash.sh](../scripts/file_hash.sh) to measure the code that the workflow ran on (including the pr\_timestamp file)
+      - Writes the hash to the pr\_hash file
   1. The internal workflow should commit the updates to pr\_timestamp and pr\_hash as the final commit to the feature branch
-    - Note that the workflow should be run upon a branch containing the MERGE of the feature branch into main, but the updated stamp files should be committed directly to the feature branch
+      - ⚠️  IMPORTANT! The workflow should be run upon a branch containing the MERGE of the feature branch into main, and this merge branch should be used to calculate the file hash. But the updated stamp files should be committed directly to the feature branch.
   1. Contributor creates a Pull Request to submit the feature branch to the GitHub `main` branch
   1. Pull Request triggers GitHub Actions to run
-    - Verilator, etc
-    - Check on the timestamp. If the timestamp is sufficiently outdated (predates the final commit to the branch by more than 1 hour) the feature branch is considered to have failed the internal workflow
-    - Pull Request runs a hash on the branch fileset (including the timestamp), compares with the contents of pr\_hash. If the hash mismatches, the feature branch is considered to have failed the internal workflow
+      - Verilator, etc
+      - Check on the timestamp. If the timestamp is sufficiently outdated (predates the final commit to the branch by more than 1 hour) the feature branch is considered to have failed the internal workflow
+      - Pull Request runs a hash on the branch fileset (including the timestamp), compares with the contents of pr\_hash. If the hash mismatches, the feature branch is considered to have failed the internal workflow
   1. Pull Request is allowed to be merged only once all Actions complete successfully
 
 The Pull Request run ignores updates to documentation files. That is, commits containing only markdown (.md) or image (.png) files are not required to pass the timestamp/hash check.

.github/workflow_metadata/pr_hash

@@ -1 +1 @@
-5079cc72ec663d8c25bb5f545971b24538e4ae2a1bfe5d7584590c59489519028b49307d13b1fbdf8aa363278684be0c
+fde9d1079e553c77020a67730f8725c220f1dd5d6d8d9ec3c1d6415f79ea7573075c3787c14674c943c9b93d45866199

.github/workflow_metadata/pr_timestamp

@@ -1 +1 @@
-1719513055
+1719520371

.github/workflows/pre-run-check.yml

@@ -114,20 +114,28 @@ jobs:
                 last_commit="$(git rev-parse ${last_commit}^)"
             done
             echo "Latest non-doc hash is ${last_commit}"
-            # Compare the timestamp from the latest commit with the pr_timestamp file
-            timestamp_exp=$(bc <<< "$(git log -n1 --pretty=tformat:'%ct' ${last_commit})-3600")
-            if [[ ! -f $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp ]]; then
-                echo "Error, file not found: $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp"
-                exit 1
-            fi
-            timestamp=$(tail -1 $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp)
-            if [[ ${timestamp} -lt ${timestamp_exp} ]]; then
-                echo "Error, submitted timestamp [${timestamp}] is outdated: it precedes the latest non-documentation commit to branch by more than an hour [${timestamp_exp}]"
-                echo "Please rerun any internal/company proprietary testcases, which should invoke .github/scripts/stamp_repo.sh to attest to successful completion"
-                echo "DO NOT manually run stamp_repo.sh on your branch to bypass this step - the output timestamp/hash is used to verify internal testcase sign-off is successful"
-                exit 1
+            # If the last non-doc commit is already contained in branch 'main', then skip the
+            # timestamp check -- as that commit would already be signed off through another PR.
+            # Otherwise, that commit would fail because it's part of a commit that was squashed into main
+            # much later than the original stamp commit.
+            if [[ $(git branch --remotes --list 'origin/main' --contains ${last_commit}) =~ 'origin/main' ]]; then
+                echo "Commit ${last_commit} is contained in branch 'main', skipping timestamp check"
+            else
+                # Compare the timestamp from the latest commit with the pr_timestamp file
+                timestamp_exp=$(bc <<< "$(git log -n1 --pretty=tformat:'%ct' ${last_commit})-3600")
+                if [[ ! -f $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp ]]; then
+                    echo "Error, file not found: $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp"
+                    exit 1
+                fi
+                timestamp=$(tail -1 $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp)
+                if [[ ${timestamp} -lt ${timestamp_exp} ]]; then
+                    echo "Error, submitted timestamp [${timestamp}] is outdated: it precedes the latest non-documentation commit to branch by more than an hour [${timestamp_exp}]"
+                    echo "Please rerun any internal/company proprietary testcases, which should invoke .github/scripts/stamp_repo.sh to attest to successful completion"
+                    echo "DO NOT manually run stamp_repo.sh on your branch to bypass this step - the output timestamp/hash is used to verify internal testcase sign-off is successful"
+                    exit 1
+                fi
+                echo "Submitted timestamp [${timestamp}] meets the recency requirement: [${timestamp_exp}]"
             fi
-            echo "Submitted timestamp [${timestamp}] meets the recency requirement: [${timestamp_exp}]"
 
       - name: Check Hash
         run: |