Documentation drop

docs/ci/actions/README.md

@@ -6,6 +6,7 @@ This repository defines several reusable [composite actions](https://docs.github
 |---|---|
 | [add-token-to-labview](../../../.github/actions/add-token-to-labview) | Adds a `LocalHost.LibraryPaths` token to the LabVIEW INI. |
 | [apply-vipc](../../../.github/actions/apply-vipc) | Installs runner dependencies for a given LabVIEW version and bitness. |
+| [auto-issue-branch](../../../.github/actions/auto-issue-branch) | Automatically creates branches for issues with required metadata; used by [auto-issue-branch workflow](../../../.github/workflows/auto-issue-branch.yml). |
 | [build](../../../.github/actions/build) | **Deprecated**: previously orchestrated the full build and packaging process. |
 | [build-lvlibp](../../../.github/actions/build-lvlibp) | Creates the editor packed library. |
 | [build-vi-package](../../../.github/actions/build-vi-package) | Updates a VIPB file and builds the VI package. |

docs/ci/actions/build-vi-package.md

@@ -152,8 +152,8 @@ components remain unchanged and only the build number increases.
 
 4. **Compute Final Version**
    - Merges the label-based bump with existing tags (if any).
-   - If on `release-alpha/*`, `release-beta/*`, or `release-rc/*`, appends `-alpha.<N>`, `-beta.<N>`, or `-rc.<N>` respectively.
-   - Always adds `-build<BUILD_NUMBER>` last, e.g. `v1.2.3-rc.5-build37`.
+   - If on `release-alpha/*`, `release-beta/*`, or `release-rc/*`, appends `-alpha.<commitCount>`, `-beta.<commitCount>`, or `-rc.<commitCount>` respectively. Here `<N>` equals the commit count, matching [`compute-version`](../../../.github/actions/compute-version/action.yml).
+   - Always adds `-build<BUILD_NUMBER>` last, e.g. `v1.2.3-rc.37-build37`. Because both values use the commit count, the pre-release number and build number are identical.
 
 5. **Build the Icon Editor VI Package**
    - Uses the `build-lvlibp` action to compile the packed libraries.
@@ -169,7 +169,7 @@ components remain unchanged and only the build number increases.
 
 ### 4.3 Pre-Release vs. Final Release
 
-- **`release-alpha/*`, `release-beta/*`, `release-rc/*`** branches → Add `-alpha.<N>`, `-beta.<N>`, or `-rc.<N>` suffixes to indicate pre-release.
+- **`release-alpha/*`, `release-beta/*`, `release-rc/*`** branches → Add `-alpha.<commitCount>`, `-beta.<commitCount>`, or `-rc.<commitCount>` suffixes to indicate pre-release. The `<N>` value equals the commit count and therefore matches the build suffix.
 - Merging back to `main` typically yields a final version with no pre-release suffix.
 - Maintainers can manually convert a pre-release to a final release after verifying assets or notes.
 
@@ -227,10 +227,10 @@ components remain unchanged and only the build number increases.
 - **Result**: Upon merging, the workflow updates that version field (major/minor/patch) and applies a commit-based build number. If the PR has no version label, the patch version is bumped by default. The `.vip` artifact is uploaded; any tagging or release must be handled separately.
 
 #### Example:
-1. PR labeled `minor`:  
+1. PR labeled `minor`:
    - Previous version: `v1.2.3-build45`
    - New version on merge: `v1.3.0-build46`
-   - If it’s `release-rc/*`, might become `v1.3.0-rc.1-build46` (`release-alpha/*` and `release-beta/*` yield `-alpha.<N>` and `-beta.<N>`).
+   - If it’s `release-rc/*`, might become `v1.3.0-rc.46-build46` (`release-alpha/*` and `release-beta/*` yield `-alpha.<commitCount>` and `-beta.<commitCount>`).
 
 ### 7.2 Direct Push to Main or Develop
 - **Scenario**: You quickly push a fix to `develop` without opening a PR.
@@ -239,7 +239,7 @@ components remain unchanged and only the build number increases.
 
 ### 7.3 Working on a Release Branch
 - **Scenario**: You branch off `release-rc/1.2`.
-- **Action**: The workflow appends `-rc.<N>` each time you commit to that pre-release branch, e.g. `v1.2.0-rc.2-build50`. Branches named `release-alpha/1.2` or `release-beta/1.2` would similarly append `-alpha.<N>` or `-beta.<N>`; these patterns correspond to the `release-alpha/*`, `release-beta/*`, and `release-rc/*` rules in `ci-composite.yml`.
+- **Action**: The workflow appends `-rc.<commitCount>` each time you commit to that pre-release branch, e.g. `v1.2.0-rc.50-build50`. Branches named `release-alpha/1.2` or `release-beta/1.2` would similarly append `-alpha.<commitCount>` or `-beta.<commitCount>`; these patterns correspond to the `release-alpha/*`, `release-beta/*`, and `release-rc/*` rules in `ci-composite.yml`.
 - **Result**: Merging `release-rc/1.2` back to `main` finalizes `v1.2.0-build51`.
 
 ### 7.4 Manually Triggering (workflow_dispatch)
@@ -306,7 +306,7 @@ components remain unchanged and only the build number increases.
 **A:** By default, we rely on `git rev-list --count HEAD`. You can change it by passing a custom environment variable or adjusting the version logic in your workflow.
 
 **Q:** Does it support alpha/beta channels out of the box?
-**A:** Yes. Branches `release-alpha/*`, `release-beta/*`, and `release-rc/*` automatically append `-alpha.<N>`, `-beta.<N>`, or `-rc.<N>` during the “Compute version string” step.
+**A:** Yes. Branches `release-alpha/*`, `release-beta/*`, and `release-rc/*` automatically append `-alpha.<commitCount>`, `-beta.<commitCount>`, or `-rc.<commitCount>` during the “Compute version string” step, so the pre-release number matches the build number.
 
 **Q:** What about manual triggers?  
 **A:** If `workflow_dispatch` is enabled, you can run it from the Actions tab, typically defaulting to the same logic (`none` for bump).

docs/ci/actions/injecting-repo-org-to-vi-package.md

@@ -44,7 +44,7 @@ We achieve this by:
 
 ## GitHub Actions and PowerShell
 
-A typical **GitHub Actions** workflow might have steps like. The composite CI workflow builds **32- and 64-bit** packed libraries separately, but the `build-vi-package` step packages only a **64-bit** VI package for **LabVIEW 2023**. The steps below mirror [`ci-composite.yml`](../../../.github/workflows/ci-composite.yml) lines 230-248 and 270-324:
+A typical **GitHub Actions** workflow might have steps like the snippet below. It is an illustrative example that condenses the process into a single job. In the actual [`ci-composite.yml`](../../../.github/workflows/ci-composite.yml) workflow, these steps are separated into the **`build-ppl`** and **`build-vi-package`** jobs. The `build-ppl` job compiles the 32- and 64-bit packed libraries, while `build-vi-package` injects the display metadata and creates the final `.vip` file. Referring to the jobs by name—rather than line numbers—helps avoid future drift. The snippet mirrors key steps such as `build-lvlibp`, `modify-vipb-display-info`, and `build-vi-package`:
 
 ```yaml
 jobs:

docs/ci/actions/maintainers-guide.md

@@ -22,10 +22,12 @@ current.
 
 1. Confirm the related GitHub issue is approved for work.
 2. Create a branch from `develop` named `issue-<number>-<short-description>`
-   (for example, `issue-123-fix-toolbar`).
-3. Set the issue's **Status** field to `In Progress`. The
-   [composite CI workflow](../../../.github/workflows/ci-composite.yml) skips
-   most jobs when the status is not set.
+   (for example, `issue-123-fix-toolbar`). Branch names **must** include
+   `issue-<number>`.
+3. Set the linked issue's **Status** field to **In Progress**. The
+   [`issue-status` job](../../../.github/workflows/ci-composite.yml)
+   enforces the branch naming and status requirements, skipping most jobs when
+   either condition is not met.
 4. Push the branch to the main repository and open a pull request targeting
    `develop` (or another appropriate branch).
 5. Run unit tests or scripted checks locally whenever possible.

docs/ci/actions/multichannel-release-workflow.md

@@ -30,7 +30,7 @@ This **Multi-Channel Release Workflow** automates packaging LabVIEW `.vip` files
 
 - Uses **label-based** semantic version increments for major/minor/patch.
 - Maintains a **commit-based build number**, so every new commit yields a unique suffix (`-buildNN`).
-- Extends pre-release logic to **Alpha**, **Beta**, and **RC** channels, not just a single `release/*` for RC.
+- Extends pre-release logic to **Alpha**, **Beta**, and **RC** channels, not just a single `release/*` for RC. The pre-release number uses the same commit count as the build number, so both values are identical.
 
 By adopting these patterns, maintainers can run alpha, beta, and RC pipelines in parallel or sequentially, each channel generating distinct pre-release versions.
 
@@ -53,15 +53,15 @@ By adopting these patterns, maintainers can run alpha, beta, and RC pipelines in
 <a name="configuration--branch-patterns"></a>
 ## **3. Configuration & Branch Patterns**
 
-1. **Alpha**  
-   - Branch pattern: `release-alpha/*`.  
-   - Produces versions like `vX.Y.Z-alpha.<N>-build<commitCount>`.  
-2. **Beta**  
-   - Branch pattern: `release-beta/*`.  
-   - Produces `vX.Y.Z-beta.<N>-build<commitCount>`.  
+1. **Alpha**
+   - Branch pattern: `release-alpha/*`.
+   - Produces versions like `vX.Y.Z-alpha.<commitCount>-build<commitCount>`.
+2. **Beta**
+   - Branch pattern: `release-beta/*`.
+   - Produces `vX.Y.Z-beta.<commitCount>-build<commitCount>`.
 3. **RC**
   - Branch pattern: `release-rc/*`.
-  - Produces `vX.Y.Z-rc.<N>-build<commitCount>`.
+  - Produces `vX.Y.Z-rc.<commitCount>-build<commitCount>`.
 4. **Other Branches**
   - `main`, `develop`, `hotfix/*` produce final releases with no alpha/beta/rc suffix.
   - No label => major/minor/patch remain unchanged; build increments only.
@@ -116,8 +116,8 @@ Below is a **high-level** breakdown. In your `.github/workflows/ci-composite.yml
 4. **Compute final version**:  
    - Parse the last stable tag (or default to `v0.0.0`).  
    - Apply major/minor/patch if needed.  
-   - If branch matches `release-alpha/*`, `release-beta/*`, or `release-rc/*`, append `-alpha.<N>`, `-beta.<N>`, or `-rc.<N>`.  
-   - Finally append `-build<commitCount>`.
+   - If branch matches `release-alpha/*`, `release-beta/*`, or `release-rc/*`, append `-alpha.<commitCount>`, `-beta.<commitCount>`, or `-rc.<commitCount>`. The `<N>` value equals the commit count.
+   - Finally append `-build<commitCount>`. Because both suffixes use the commit count, the pre-release number and build number are identical.
 
 <a name="build--artifact-handling"></a>
 ### **Build & Artifact Handling**
@@ -157,8 +157,8 @@ Any commit to these branches triggers an alpha/beta/rc suffix. Merging to `main`
      $preSuffix = ""
    }
    ```
-2. If `$preSuffix` is non-empty, `isPrerelease = true`.  
-3. Final version: `v<major>.<minor>.<patch>-<preSuffix>-build<commitCount>`.
+2. If `$preSuffix` is non-empty, `isPrerelease = true`.
+3. Final version: `v<major>.<minor>.<patch>-<preSuffix>-build<commitCount>`. Since `<preSuffix>` incorporates `$commitsCount`, the pre-release number and build number are the same.
 
 <a name="final-release-flow"></a>
 ### **5.3 Final Release Flow**
@@ -169,17 +169,17 @@ Any commit to these branches triggers an alpha/beta/rc suffix. Merging to `main`
 <a name="usage-examples"></a>
 ## **6. Usage Examples**
 
-1. **Alpha Channel Testing**  
-   - You want an early test for version 2.0: create `release-alpha/2.0`.  
-   - Each commit produces something like `v2.0.0-alpha.2-build41`.  
+1. **Alpha Channel Testing**
+   - You want an early test for version 2.0: create `release-alpha/2.0`.
+   - Each commit produces something like `v2.0.0-alpha.41-build41`.
    - Merging alpha → beta or main finalizes or transitions the channel.
 
-2. **Beta Channel**  
-   - `release-beta/2.0`. Now each commit yields `v2.0.0-beta.3-build45`.  
+2. **Beta Channel**
+   - `release-beta/2.0`. Now each commit yields `v2.0.0-beta.45-build45`.
    - Merging back to `main` yields a stable `v2.0.0-build46`.
 
-3. **RC Branch**  
-   - `release-rc/2.1`. The workflow sets `-rc.<N>` so your testers see it’s near final.  
+3. **RC Branch**
+   - `release-rc/2.1`. The workflow sets `-rc.<commitCount>` so your testers see it’s near final, e.g. `v2.1.0-rc.50-build50`.
    - Merging to main ends the RC, resulting in `v2.1.0-buildXX`.
 
 4. **No Pre-Release**  
@@ -224,4 +224,4 @@ Any commit to these branches triggers an alpha/beta/rc suffix. Merging to `main`
 <a name="conclusion"></a>
 ## **9. Conclusion**
 
-By supporting **multiple pre-release channels** (Alpha, Beta, RC), this updated release workflow offers greater flexibility for iterative testing stages. Each branch pattern yields a distinct suffix (`-alpha.<N>`, `-beta.<N>`, or `-rc.<N>`). Merging into a final branch (e.g., `main`) produces a stable release with no suffix, but still uses **commit-based** build numbering. Combined with label-based major/minor/patch increments, you have a **robust**, **fork-friendly**, and **multi-stage** CI/CD pipeline for LabVIEW. 
+By supporting **multiple pre-release channels** (Alpha, Beta, RC), this updated release workflow offers greater flexibility for iterative testing stages. Each branch pattern yields a distinct suffix (`-alpha.<commitCount>`, `-beta.<commitCount>`, or `-rc.<commitCount>`). Merging into a final branch (e.g., `main`) produces a stable release with no suffix, but still uses **commit-based** build numbering—so the pre-release number and build number are always identical. Combined with label-based major/minor/patch increments, you have a **robust**, **fork-friendly**, and **multi-stage** CI/CD pipeline for LabVIEW.

docs/ci/troubleshooting-faq.md

@@ -12,7 +12,7 @@ This document provides a collection of common **troubleshooting** scenarios (wit
    3. [No. 3: Version Label Not Recognized](#no-3-version-label-not-recognized)
    4. [No. 4: Build Number Not Updating](#no-4-build-number-not-updating)
    5. [No. 5: Dev Mode Still Enabled After Build](#no-5-dev-mode-still-enabled-after-build)
-   6. [No. 6: Release Not Created or Drafted](#no-6-release-not-created-or-drafted)
+   6. [No. 6: Release Not Created](#no-6-release-not-created)
    7. [No. 7: Branch Protection Blocks Merge](#no-7-branch-protection-blocks-merge)
    8. [No. 8: Incorrect Pre-Release Suffix (Alpha/Beta/RC)](#no-8-incorrect-pre-release-suffix-alphabetarc)
    9. [No. 9: Hotfix Not Tagged as Expected](#no-9-hotfix-not-tagged-as-expected)
@@ -24,11 +24,11 @@ This document provides a collection of common **troubleshooting** scenarios (wit
 
 2. [FAQ](#faq)
    1. [Q1: Can I Override the Build Number?](#q1-can-i-override-the-build-number)
-   2. [Q2: How Do I Skip Creating a Release?](#q2-how-do-i-skip-creating-a-release)
+   2. [Q2: How Do I Create a Release?](#q2-how-do-i-create-a-release)
    3. [Q3: Can I Have More Than Alpha, Beta, or RC Channels?](#q3-can-i-have-more-than-alpha-beta-or-rc-channels)
    4. [Q4: How Can I Attach Multiple `.vip` Files to a Release?](#q4-how-can-i-attach-multiple-vip-files-to-a-release)
    5. [Q5: Do I Need To Merge Hotfixes Into `develop`?](#q5-do-i-need-to-merge-hotfixes-into-develop)
-   6. [Q6: What If I Don’t Want a Draft Release?](#q6-what-if-i-dont-want-a-draft-release)
+   6. [Q6: What About Draft Releases?](#q6-what-about-draft-releases)
    7. [Q7: Can I Use This Workflow Without Gitflow?](#q7-can-i-use-this-workflow-without-gitflow)
    8. [Q8: Why Is My Dev Mode Toggle Not Working Locally?](#q8-why-is-my-dev-mode-toggle-not-working-locally)
    9. [Q9: Can I Use a Different LabVIEW Version (e.g., 2023)?](#q9-can-i-use-a-different-labview-version-eg-2023)
@@ -123,18 +123,18 @@ Below are 13 possible issues you might encounter, along with suggested steps to
 
 ---
 
-### No. 6: Release Not Created or Drafted
+### No. 6: Release Not Created
 
 **Symptoms**:
 - The workflow completes, but you see no new release in GitHub’s “Releases” section.
 
 **Possible Causes**:
-- `DRAFT_RELEASE` is set to `true` (so it’s in draft state), or the “Create Release” step was skipped.
+- The composite pipeline only uploads artifacts and does not create releases automatically.
 - The build was triggered by a Pull Request, and your workflow logic only creates releases on “push” or merges to main.
 
 **Solution**:
-1. Check your workflow triggers: releases are often created only on direct pushes to specific branches.  
-2. If `DRAFT_RELEASE == true`, look in “Releases → Drafts” to publish it manually.  
+1. Create releases manually through GitHub’s interface or configure a separate workflow to publish them.
+2. Check your workflow triggers if you expect another workflow to handle releases on certain branches.
 3. Confirm you have “Read and write” permissions for Actions in your repo settings.
 
 ---
@@ -261,10 +261,10 @@ By default, the workflow calculates the build number with `git rev-list --count
 
 ---
 
-### Q2: How Do I Skip Creating a Release?
+### Q2: How Do I Create a Release?
 
-**Answer**:  
-You can set an environment variable like `CREATE_RELEASE=false` (if your workflow supports it) or remove the “Create Release” step for certain branches. Another option is to let it create a draft release and simply never publish it.
+**Answer**:
+The composite pipeline only uploads artifacts and does not create GitHub releases automatically. Create releases manually through the GitHub interface or set up a separate workflow dedicated to publishing them.
 
 ---
 
@@ -289,10 +289,10 @@ Yes. In standard Gitflow, after merging a `hotfix/*` into `main`, you also merge
 
 ---
 
-### Q6: What If I Don’t Want a Draft Release?
+### Q6: What About Draft Releases?
 
-**Answer**:  
-Simply set `DRAFT_RELEASE=false`. The release will be published immediately after the workflow completes. Alternatively, you can remove or tweak that setting in your `.yml` file.
+**Answer**:
+The composite pipeline doesn’t create releases, so draft releases are not generated. If you require a draft or published release, create it manually or configure a separate workflow to handle release creation.
 
 ---
 
@@ -319,8 +319,18 @@ Yes, if your machine and project support it. You’ll need to install that versi
 
 ### Q10: How Do I Pass Repository Name and Organization?
 
-**Answer**:  
-Inside **GitHub Actions**, you can reference environment variables such as `${{ github.repository_owner }}` and `${{ github.repository }}`. Pass them to your script (for example, `-CompanyName "$env:REPO_OWNER"` and `-AuthorName "$env:REPO_NAME"`), which then gets injected into the `DisplayInformationJSON` used by `build_vip.ps1`. This ensures each build is branded with your fork’s or org’s name.
+**Answer**:
+Inside **GitHub Actions**, you can reference environment variables such as `${{ github.repository_owner }}` and `${{ github.event.repository.name }}`. Set them first in your workflow step and then pass them to your script:
+
+```yaml
+env:
+  REPO_OWNER: ${{ github.repository_owner }}
+  REPO_NAME: ${{ github.event.repository.name }}
+run: |
+  .\build_vip.ps1 -CompanyName "$env:REPO_OWNER" -AuthorName "$env:REPO_NAME"
+```
+
+`${{ github.repository }}` returns `owner/repo`, so it isn’t suitable for the author field. Using the separate owner and repository values ensures your build is branded correctly when `DisplayInformationJSON` is injected by `build_vip.ps1`.
 
 ---