Update of linting workflows

.github/workflows/pr_validation_caller.yml

@@ -1,29 +1,49 @@
+# =========================================================================================
+# CAMARA Project - Pull Request Validation Workflow Caller
+#
+# This GitHub Actions workflow is responsible for invoking a reusable PR validation workflow
+# from the camaraproject/tooling repository. It is intended to ensure consistent validation
+# steps for all PRs targeting the main branch in this repository.
+#
+# CHANGELOG:
+# - 2025-08-01: Initial version for v0
+#
+# USAGE:
+# - Automatically triggers on pull requests targeting main.
+# - Can be triggered manually via workflow_dispatch.
+# - Calls by default the reusable workflow at 
+#   camaraproject/tooling/.github/workflows/pr_validation.yml@v0
+#
+# DOCUMENTATION:
+# see https://github.com/camaraproject/tooling/tree/main/linting/docs
+# =========================================================================================
+
 name: Caller for PR validation workflow
-# CAMARA Project - Github Action for Pull Reqests
-# This workflow calls the reusable workflow from the tooling repository
-# initial version
 
 on:
-  # Pull Requests to main
+  # Trigger on pull requests to the main branch only
   pull_request:
     branches: main
-  # manual workflow triggering
+  # Enable manual trigger via the GitHub UI
   workflow_dispatch:
 
 concurrency:
   group: ${{ github.ref }}-${{ github.workflow }}
   cancel-in-progress: true
 
 permissions:
+  # Grant necessary write permissions for PRs, contents, and issues
   pull-requests: write
   contents: write
   issues: write
+  statuses: write
 
 jobs:
   pr_validation:
-    uses: camaraproject/tooling/.github/workflows/pr_validation.yml@main
+    # Invoke the reusable PR validation workflow from "v0" tag of camaraproject/tooling
+    uses: camaraproject/tooling/.github/workflows/pr_validation.yml@v0
     secrets: inherit
-# This workflow calls the reusable workflow from tooling repository
-# Tools configuration from the tooling repository branch indicated by `configurations` variable    
+# Tools configuration from the tooling repository subfolder of /linting/config/ indicated by `configurations` variable
+# If needed, you can specify a configuration from another subfolder of camaraproject/tooling/linting/config/ (uncomment below)
 #    with:
-#      configurations: staging
+#      configurations: api-name

.github/workflows/spectral-oas-caller.yml

@@ -1,7 +1,23 @@
+# =========================================================================================
+# CAMARA Project - Linting OpenAPI Specification with CAMARA Ruleset Caller
+#
+# This GitHub Actions workflow is responsible for invoking a reusable "Spectral linting with 
+# CAMARA ruleset" workflow from the camaraproject/tooling repository. It is intended to 
+# provide more detailed output from Spectral tool (warnings, hints)  
+#
+# CHANGELOG:
+# - 2025-08-01: Initial version for v0
+#
+# USAGE:
+# - Can be triggered manually via workflow_dispatch.
+# - Calls by default the reusable workflow at 
+#   camaraproject/tooling/.github/workflows/spectral-oas.yml@v0
+#
+# DOCUMENTATION:
+# see https://github.com/camaraproject/tooling/tree/main/linting/docs
+# =========================================================================================
+
 name: Caller for Spectral linting with CAMARA ruleset
-# CAMARA Project - Github Action for Pull Reqests
-# This workflow calls the reusable workflow from the tooling repository
-# initial version
 
 on: 
   workflow_dispatch:
@@ -11,14 +27,16 @@ concurrency:
   cancel-in-progress: true
 
 permissions:
+  # Grant necessary write permissions for PRs and issues
   pull-requests: write
-  contents: write
+  contents: read
   issues: write
 
 jobs:
   spectral:
-    uses: camaraproject/tooling/.github/workflows/spectral-oas.yml@main
-# This workflow calls the reusable workflow from the tooling repository
-# Tools configuration from the tooling repository branch indicated by `configurations` variable    
+  # Invoke the reusable PR validation workflow from the main branch of camaraproject/tooling
+    uses: camaraproject/tooling/.github/workflows/spectral-oas.yml@v0
+# Spectral configuration from the tooling repository subfolder of /linting/config/ indicated by `configurations` variable
+# If needed, you can specify a configuration from another subfolder of camaraproject/tooling/linting/config/ (uncomment below)
 #    with:
-#      configurations: staging
+#      configurations: api-name