workflows: standardize pkg-* workflow naming

.github/pkg-workflows/debian/pr-pre-post-merge.yml → .github/pkg-workflows/debian/pkg-pr-hook.yml

@@ -37,7 +37,7 @@ jobs:
     name: Build Debian Package
     needs: resolve-suite
     if: ${{ github.event.action != 'closed' || github.event.pull_request.merged == true }}
-    uses: qualcomm-linux/qcom-build-utils/.github/workflows/qcom-build-pkg-reusable-workflow.yml@main
+    uses: qualcomm-linux/qcom-build-utils/.github/workflows/pkg-build-reusable-workflow.yml@main
     with:
       qcom-build-utils-ref: main
       # PRE-MERGE: use the PR head branch (github.head_ref)

.github/pkg-workflows/main/build-debian-package.yml → .github/pkg-workflows/main/pkg-build.yml

@@ -37,7 +37,7 @@ permissions:
 
 jobs:
   build:
-    uses: qualcomm-linux/qcom-build-utils/.github/workflows/qcom-build-pkg-reusable-workflow.yml@main
+    uses: qualcomm-linux/qcom-build-utils/.github/workflows/pkg-build-reusable-workflow.yml@main
     with:
       qcom-build-utils-ref: main
       debian-ref: ${{ inputs.debian-ref }}

.github/pkg-workflows/main/promote-prebuilt.yml → .github/pkg-workflows/main/pkg-promote-prebuilt.yml

@@ -40,7 +40,7 @@ permissions:
 
 jobs:
   promote:
-    uses: qualcomm-linux/qcom-build-utils/.github/workflows/qcom-promote-prebuilt-reusable-workflow.yml@dev/pkg-bin
+    uses: qualcomm-linux/qcom-build-utils/.github/workflows/pkg-promote-prebuilt-reusable-workflow.yml@dev/pkg-bin
     with:
       qcom-build-utils-ref: dev/pkg-bin
       debian-branch: ${{inputs.debian-branch}}

.github/pkg-workflows/main/promote-upstream.yml → .github/pkg-workflows/main/pkg-promote.yml

@@ -23,7 +23,7 @@ permissions:
 jobs:
   promote:
 
-    uses: qualcomm-linux/qcom-build-utils/.github/workflows/qcom-promote-upstream-reusable-workflow.yml@main
+    uses: qualcomm-linux/qcom-build-utils/.github/workflows/pkg-promote-reusable-workflow.yml@main
     with:
       qcom-build-utils-ref: main
       debian-branch: ${{inputs.debian-branch}}

.github/pkg-workflows/main/release.yml → .github/pkg-workflows/main/pkg-release.yml

@@ -41,7 +41,7 @@ permissions:
 jobs:
   release:
 
-    uses: qualcomm-linux/qcom-build-utils/.github/workflows/qcom-release-reusable-workflow.yml@main
+    uses: qualcomm-linux/qcom-build-utils/.github/workflows/pkg-release-reusable-workflow.yml@main
     with:
       qcom-build-utils-ref: main
       suite: ${{ github.event.inputs.suite }}

.github/workflows/qcom-promote-prebuilt-reusable-workflow.yml → .github/workflows/pkg-promote-prebuilt-reusable-workflow.yml

@@ -1,7 +1,7 @@
 name: Qualcomm Prebuilt Binary Promotion Reusable Workflow
 description: |
   This reusable workflow promotes a binary package repo to a new Artifactory release.
-  Unlike the source-based qcom-promote-upstream-reusable-workflow, this workflow does
+  Unlike the source-based pkg-promote-reusable-workflow, this workflow does
   not interact with any upstream git repository. Instead it:
     1. Reads the current upstream.conf from the packaging branch.
     2. Verifies the new tarball actually exists on Artifactory before making any changes.

.github/workflows/qcom-release-reusable-workflow.yml → .github/workflows/pkg-release-reusable-workflow.yml

@@ -109,7 +109,7 @@ jobs:
     name: Build and Test (Debian)
     if: ${{ needs.resolve.outputs.family == 'debian' }}
     needs: resolve
-    uses: ./.github/workflows/qcom-build-pkg-reusable-workflow.yml
+    uses: ./.github/workflows/pkg-build-reusable-workflow.yml
     with:
       qcom-build-utils-ref: ${{ inputs.qcom-build-utils-ref }}
       debian-ref: ${{ inputs.debian-branch }}

.github/workflows/workflows_sync.yml

@@ -60,9 +60,11 @@ jobs:
 
           echo "List of repositories starting with 'pkg-': $repos"
 
-          # pr-pre-post-merge.yml is checked out locally in pkg-workflows/debian/
-          DEBIAN_LATEST_WORKFLOW_FILE="$(pwd)/qcom-build-utils/.github/pkg-workflows/debian/pr-pre-post-merge.yml"
-          echo "📄 Using pr-pre-post-merge.yml from pkg-workflows/debian/"
+          # pkg-pr-hook.yml is checked out locally in pkg-workflows/debian/
+          DEBIAN_LATEST_WORKFLOW_FILE="$(pwd)/qcom-build-utils/.github/pkg-workflows/debian/pkg-pr-hook.yml"
+          DEBIAN_TARGET_WORKFLOW_FILE=".github/workflows/pkg-pr-hook.yml"
+          DEBIAN_LEGACY_WORKFLOW_FILE=".github/workflows/pr-pre-post-merge.yml"
+          echo "📄 Using pkg-pr-hook.yml from pkg-workflows/debian/"
 
           for repo in $repos; do
             # Skip excluded repositories
@@ -121,6 +123,17 @@ jobs:
               isDirty=true
             fi
 
+            # Remove legacy main-branch caller workflow names. New names are
+            # synced from .github/pkg-workflows/main/*.yml below.
+            for legacy_main_workflow in build-debian-package.yml promote-prebuilt.yml promote-upstream.yml release.yml; do
+              legacy_main_path=".github/workflows/$legacy_main_workflow"
+              if [[ -f "$legacy_main_path" ]]; then
+                echo "    🗑️ Removing legacy workflow: $legacy_main_workflow"
+                rm "$legacy_main_path"
+                isDirty=true
+              fi
+            done
+
             # Compare and sync workflow files
             for workflow in ../qcom-build-utils/.github/pkg-workflows/main/*.yml; do
               workflow_name=$(basename "$workflow")
@@ -172,7 +185,7 @@ jobs:
                 echo "    ✨ No main branch changes needed for $repo"
               fi
 
-              # Sync pr-pre-post-merge.yml from qcom-build-utils pkg-workflows
+              # Sync pkg-pr-hook.yml from qcom-build-utils pkg-workflows
               # to every debian/* and qcom/debian/* branch
               debian_branches=$(git branch -r | grep -E 'origin/(qcom/)?debian/' | sed 's|.*origin/||' | tr -d ' ')
 
@@ -182,9 +195,9 @@ jobs:
                   continue
                 fi
 
-                echo "  🌿 Checking pr-pre-post-merge.yml on branch: $debian_branch"
+                echo "  🌿 Checking pkg-pr-hook.yml on branch: $debian_branch"
                 safe_branch_name="${debian_branch//\//-}"
-                debian_sync_branch="sync/qcom-build-utils-pr-merge-${safe_branch_name}"
+                debian_sync_branch="sync/qcom-build-utils-pkg-pr-hook-${safe_branch_name}"
 
                 # Delete existing sync branch if from a previous run
                 if git ls-remote --exit-code --heads origin "$debian_sync_branch" > /dev/null 2>&1; then
@@ -195,33 +208,40 @@ jobs:
                 git checkout "$debian_branch" 2>&1 | sed 's/^/    /'
 
                 isDebianDirty=false
-                if [[ -f ".github/workflows/pr-pre-post-merge.yml" ]]; then
-                  if diff -q "$DEBIAN_LATEST_WORKFLOW_FILE" ".github/workflows/pr-pre-post-merge.yml" > /dev/null; then
-                    echo "    ✅ pr-pre-post-merge.yml is up to date on $debian_branch"
+
+                if [[ -f "$DEBIAN_LEGACY_WORKFLOW_FILE" ]]; then
+                  echo "    🗑️ Removing legacy pr-pre-post-merge.yml on $debian_branch"
+                  rm "$DEBIAN_LEGACY_WORKFLOW_FILE"
+                  isDebianDirty=true
+                fi
+
+                if [[ -f "$DEBIAN_TARGET_WORKFLOW_FILE" ]]; then
+                  if diff -q "$DEBIAN_LATEST_WORKFLOW_FILE" "$DEBIAN_TARGET_WORKFLOW_FILE" > /dev/null; then
+                    echo "    ✅ pkg-pr-hook.yml is up to date on $debian_branch"
                   else
-                    echo "    ❌ pr-pre-post-merge.yml differs on $debian_branch"
-                    cp "$DEBIAN_LATEST_WORKFLOW_FILE" ".github/workflows/pr-pre-post-merge.yml"
+                    echo "    ❌ pkg-pr-hook.yml differs on $debian_branch"
+                    cp "$DEBIAN_LATEST_WORKFLOW_FILE" "$DEBIAN_TARGET_WORKFLOW_FILE"
                     isDebianDirty=true
                   fi
                 else
-                  echo "    + Creating pr-pre-post-merge.yml on $debian_branch (missing)"
+                  echo "    + Creating pkg-pr-hook.yml on $debian_branch (missing)"
                   mkdir -p ".github/workflows"
-                  cp "$DEBIAN_LATEST_WORKFLOW_FILE" ".github/workflows/pr-pre-post-merge.yml"
+                  cp "$DEBIAN_LATEST_WORKFLOW_FILE" "$DEBIAN_TARGET_WORKFLOW_FILE"
                   isDebianDirty=true
                 fi
 
                 if [[ "$isDebianDirty" == "true" ]]; then
                   git checkout -b "$debian_sync_branch" 2>&1 | sed 's/^/    /'
-                  git add .github/workflows/pr-pre-post-merge.yml
-                  git commit -s -m "chore: sync pr-pre-post-merge from qcom-build-utils" 2>&1 | sed 's/^/    /'
+                  git add -A .github/workflows/
+                  git commit -s -m "chore: sync pkg-pr-hook from qcom-build-utils" 2>&1 | sed 's/^/    /'
 
                   if [[ "$CONFIRMATION_INPUT" == "true" ]]; then
                     echo "    🚀 Pushing changes and creating PR for $debian_branch"
                     git push origin "$debian_sync_branch" 2>&1 | sed 's/^/    /'
 
                     pr_url=$(gh pr create --repo "$ORG/$repo" \
-                      --title "chore: sync pr-pre-post-merge from qcom-build-utils" \
-                      --body "This PR syncs \`pr-pre-post-merge.yml\` from qcom-build-utils \`.github/pkg-workflows/debian/\`." \
+                      --title "chore: sync pkg-pr-hook from qcom-build-utils" \
+                      --body "This PR syncs \`pkg-pr-hook.yml\` from qcom-build-utils \`.github/pkg-workflows/debian/\`." \
                       --head "$debian_sync_branch" \
                       --base "$debian_branch")
 

AGENTS.md

@@ -8,7 +8,7 @@ orchestration around build, test, promotion, and release flows.
 
 ## Current Build/Release Architecture
 
-- Package repos call `qcom-build-pkg-reusable-workflow.yml` and `qcom-release-reusable-workflow.yml`.
+- Package repos call `pkg-build-reusable-workflow.yml` and `pkg-release-reusable-workflow.yml`.
 - Those workflows are now **hybrid**:
   - Debian suites (`trixie`, `sid`, `unstable`, `bookworm`, `forky`) use
     `qualcomm-linux/debusine-action` and Debusine builder images
@@ -25,15 +25,23 @@ orchestration around build, test, promotion, and release flows.
   published from `qualcomm-linux/debusine-action`, while the Ubuntu-capable `pkg-builder` images
   are still consumed from GHCR by the local path.
 
+## Workflow Naming Convention
+
+- `pkg-*` workflow names are for package lifecycle flows (`build`, `promote`, `release`, and
+  package PR hooks).
+- `qcom-*` workflow names are reserved for qcom-wide infrastructure and preflight flows that are
+  installed broadly (for example `qcom-preflight-checks.yml`).
+- Keep this split so package-specific automation remains easy to identify in `pkg-*` repositories.
+
 ## Important Workflows
 
-- `.github/workflows/qcom-build-pkg-reusable-workflow.yml`
+- `.github/workflows/pkg-build-reusable-workflow.yml`
   - main hybrid package build/test entrypoint for package repos
-- `.github/workflows/qcom-release-reusable-workflow.yml`
+- `.github/workflows/pkg-release-reusable-workflow.yml`
   - hybrid release entrypoint: Debian via Debusine, Ubuntu via pkg-builder + S3 flow
-- `.github/workflows/qcom-promote-upstream-reusable-workflow.yml`
+- `.github/workflows/pkg-promote-reusable-workflow.yml`
   - upstream-to-packaging promotion flow
-- `.github/workflows/qcom-upstream-pr-pkg-build-reusable-workflow.yml`
+- `.github/workflows/pkg-upstream-pr-build-reusable-workflow.yml`
   - validate upstream PRs against the Debian packaging build
 
 ## Important Debian/Debusine Helper Entrypoints

README.md

@@ -42,10 +42,10 @@ qcom-build-utils/
 │   │   ├── build_package/        # Debian package build (gbp + sbuild)
 │   │   └── push_to_repo/         # Publish packages to staging APT repo
 │   └── workflows/                # Reusable workflow definitions
-│       ├── qcom-build-pkg-reusable-workflow.yml
-│       ├── qcom-promote-upstream-reusable-workflow.yml
-│       ├── qcom-upstream-pr-pkg-build-reusable-workflow.yml
-│       ├── qcom-release-reusable-workflow.yml
+│       ├── pkg-build-reusable-workflow.yml
+│       ├── pkg-promote-reusable-workflow.yml
+│       ├── pkg-upstream-pr-build-reusable-workflow.yml
+│       ├── pkg-release-reusable-workflow.yml
 │       └── qcom-preflight-checks.yml
 ├── scripts/                      # Python & shell build utilities
 │   ├── deb_abi_checker.py        # ABI comparison tool (libabigail)
@@ -71,12 +71,16 @@ Package repositories call these workflows from their own `.github/workflows/` di
 
 | Workflow | Purpose |
 |----------|---------|
-| **qcom-build-pkg-reusable-workflow** | Main package build workflow — routes Debian suites through Debusine and Ubuntu codenames through the local pkg-builder path. |
-| **qcom-promote-upstream-reusable-workflow** | Promotes a new upstream release into a package repo — merges upstream code, updates changelog, and creates a PR. |
-| **qcom-upstream-pr-pkg-build-reusable-workflow** | Validates that PRs in an upstream repo won't break the Debian package build. Called from the upstream repo. |
-| **qcom-release-reusable-workflow** | Triggers a formal release — Debian suites use Debusine publish, Ubuntu codenames keep the local pkg-builder/S3 release path. |
+| **pkg-build-reusable-workflow** | Main package build workflow — routes Debian suites through Debusine and Ubuntu codenames through the local pkg-builder path. |
+| **pkg-promote-reusable-workflow** | Promotes a new upstream release into a package repo — merges upstream code, updates changelog, and creates a PR. |
+| **pkg-upstream-pr-build-reusable-workflow** | Validates that PRs in an upstream repo won't break the Debian package build. Called from the upstream repo. |
+| **pkg-release-reusable-workflow** | Triggers a formal release — Debian suites use Debusine publish, Ubuntu codenames keep the local pkg-builder/S3 release path. |
 | **qcom-preflight-checks** | Security and quality gates — runs repolinter, semgrep, license checks, and dependency review. |
 
+`pkg-*` and `qcom-*` naming intentionally distinguish scope:
+- `pkg-*` workflows are package-lifecycle workflows used by `pkg-*` repositories.
+- `qcom-*` workflows are qcom-wide infrastructure/preflight workflows.
+
 ## Builder Images
 
 `qcom-build-utils` consumes two image families:
@@ -104,7 +108,7 @@ The Debusine-specific helper scripts used by the Debian path are checked out fro
 3. Set repository variables:
    - **`UPSTREAM_REPO_GITHUB_NAME`** — in the **package repo**, points to the upstream source repo (e.g., `qualcomm-linux/qcom-example-package-source`).
    - **`PKG_REPO_GITHUB_NAME`** — in the **upstream repo**, points to the package repo (e.g., `qualcomm-linux/pkg-example`).
-4. Configure branch protection for `debian/qcom-next` with `build / build-debian-package` as a required status check.
+4. Configure branch protection for `debian/qcom-next` with the `pkg-build.yml` workflow check as a required status check.
 5. Copy `.github/TO_PASTE_IN_UPSTREAM_REPO/pkg-build-pr-check.yml` into the upstream repo's `.github/workflows/` on its default branch.
 
 See [pkg-example](https://github.com/qualcomm-linux/pkg-example) for a complete working reference.

docs/package-repo-integration.md

@@ -210,7 +210,7 @@ permissions:
 
 jobs:
   build:
-    uses: qualcomm-linux/qcom-build-utils/.github/workflows/qcom-build-pkg-reusable-workflow.yml@development
+    uses: qualcomm-linux/qcom-build-utils/.github/workflows/pkg-build-reusable-workflow.yml@development
     with:
       qcom-build-utils-ref: development
       debian-ref: ${{github.head_ref}}
@@ -236,7 +236,7 @@ permissions:
 
 jobs:
   build:
-    uses: qualcomm-linux/qcom-build-utils/.github/workflows/qcom-build-pkg-reusable-workflow.yml@development
+    uses: qualcomm-linux/qcom-build-utils/.github/workflows/pkg-build-reusable-workflow.yml@development
     with:
       qcom-build-utils-ref: development
       debian-ref: debian/qcom-next
@@ -257,7 +257,7 @@ For Debian suites, it uses a separate secret model from the build callers:
 - `DEBUSINE_RELEASE_TOKEN`: separate repository or organization secret used only for the final Debusine prod publish step
 
 Package repositories pass `DEBUSINE_RELEASE_TOKEN` directly to
-`qcom-release-reusable-workflow.yml` as a named secret so the reusable workflow
+`pkg-release-reusable-workflow.yml` as a named secret so the reusable workflow
 can publish the successful Debusine CI workspace and push the release git state
 without expanding the caller workflow. Ubuntu releases keep using the older
 local `pkg-builder` + S3 path and do not use those Debusine secrets.
@@ -394,7 +394,7 @@ opts=filenamemangle=s/.+\/v?(\d\S+)\.tar\.gz/mypackage-$1\.tar\.gz/ \
 
 #### Upstream Promotion Workflow
 
-Create `.github/workflows/promote-upstream.yml`:
+Create `.github/workflows/pkg-promote.yml`:
 
 ```yaml
 name: Promote Upstream Version
@@ -414,7 +414,7 @@ permissions:
 
 jobs:
   promote:
-    uses: qualcomm-linux/qcom-build-utils/.github/workflows/qcom-promote-upstream-reusable-workflow.yml@development
+    uses: qualcomm-linux/qcom-build-utils/.github/workflows/pkg-promote-reusable-workflow.yml@development
     with:
       qcom-build-utils-ref: development
       upstream-tag: ${{ github.event.inputs.upstream-tag }}
@@ -425,7 +425,7 @@ jobs:
 #### Triggering Upstream Promotion
 
 ```bash
-gh workflow run promote-upstream.yml \
+gh workflow run pkg-promote.yml \
   -f upstream-tag=v2.0.0 \
   -f upstream-repo=upstream-org/upstream-repo
 ```
@@ -491,7 +491,7 @@ permissions:
 
 jobs:
   package-build-pr-check:
-    uses: qualcomm-linux/qcom-build-utils/.github/workflows/qcom-upstream-pr-pkg-build-reusable-workflow.yml@development
+    uses: qualcomm-linux/qcom-build-utils/.github/workflows/pkg-upstream-pr-build-reusable-workflow.yml@development
     with:
       qcom-build-utils-ref: development
       upstream-repo: ${{github.repository}}           # Current upstream repo