This document provides everything you need to understand, configure, and troubleshoot the Build VI Package GitHub Action for the LabVIEW Icon Editor. It covers why we use semantic versioning, how the build number is calculated, what happens on a fork, and step-by-step instructions for various usage scenarios.

---

1. Introduction
2. Getting Started
3. Detailed Technical Section
   • How the Workflow Operates
   • Version Bumping Logic
   • Global Build Number & Tagging
   • Fork Handling and GPG Signing
4. Troubleshooting
5. FAQ

---

The Build VI Package GitHub Action provides a continuous integration (CI) and release pipeline for the LabVIEW Icon Editor project. Key highlights:

• Semantic Versioning: We automatically increment Major, Minor, or Patch based on Pull Request labels.
• Global Build Number: Each release increments a build number by counting how many prior version tags exist.
• Support for Forks: We temporarily disable GPG signing if you aren’t in the main ni/labview-icon-editor repository.
• Pre-Releases on release/* branches and final releases on merges to main or hotfix branches.

By the end of this guide, you’ll know how to:

1. Label a PR or push a commit to produce a Major, Minor, or Patch version.
2. Generate pre-release (RC) tags vs. final releases.
3. Troubleshoot common issues and adapt the workflow for your own use cases.

---

Follow these steps to use the Build VI Package Action:

1. Ensure the Workflow File Exists

   • In your repo, go to .github/workflows/build-vi-package.yml. Confirm it has the final PowerShell-based script.

2. Check Permissions

   • Under Repository → Settings → Actions, ensure “Workflow Permissions” are set to “Read and write.” This lets the Action push tags and create releases.

3. Open a Pull Request

   • If you open a PR, apply a label: major, minor, or patch.
   • The workflow tests the build and calculates a version but doesn’t push tags or create a release until merge.

4. Merge

   • If you merge a release/* branch, you get a pre-release (-rc.<N>).
   • If you merge into main or from hotfix/*, you get a final release version (no -rc).

5. Check Artifacts

   • After a successful build, the .vip file is uploaded as a GitHub Artifact.
   • A GitHub Release is created referencing the new tag.

---

Below is the deeper dive into how the workflow operates, including the version bump logic, global build numbering, and special handling for forks.

• Triggers: On push or pull request to main, develop, release/*, or hotfix/*. Also on manual workflow_dispatch.
• Checkout & Tag Analysis: We do a full-depth clone so we see all tags.
• Label Enforcement (PR-only): Fails if you haven’t labeled your PR with major, minor, or patch.
• Version Bumping: If it’s a push without a PR label, we default to patch.
• Tag Counting: We list tags matching v*.*.*-build*. That total count + 1 → new build number.
• Create & Push Tag: If not a PR, we push the new tag and create a GitHub Release.

1. PR with major label → increment Major. Reset Minor, Patch = 0.
2. PR with minor label → increment Minor. Reset Patch = 0.
3. PR with patch label → increment Patch.
4. No label or direct push → increment Patch by default.

For example:

• Current version: v1.2.3-build45
• major → v2.0.0-build46
• minor → v1.3.0-build46
• patch → v1.2.4-build46

• Count Existing Tags matching v*.*.*-build*.
• The new build = (# of matching tags) + 1.
• We append -build<Number> to the new version (e.g. v1.2.4-build46).
• If the branch is release/*, we also append -rc.<N> (e.g. v1.2.4-rc.2-build46).
• After computing this version, we do:

  git tag -a $VERSION -m "Auto-tag by CI for $VERSION"
  git push origin $VERSION

  resulting in a unique tag each time.

• If github.repository != 'ni/labview-icon-editor', we assume we’re on a fork.
• We disable commit.gpgsign and tag.gpgsign globally, because the fork can’t sign using the main repo’s GPG keys.
• We record the old config so we can restore it after the workflow finishes.

---

Below are some common issues and how to fix them:

1. “The term 'VERSION=...' is not recognized”
   • That’s a Bash-style variable assignment. Make sure you’re using $VERSION = "..." in PowerShell.
2. 403 Permission
   • If you see “Resource not accessible by integration,” your token or environment might be restricted. Check “Settings → Actions → Workflow Permissions.”
3. Tag or Release Not Created
   • Possibly you used a Pull Request event. The workflow only tags on push, not PR. Or the step might be skipped if the build failed earlier.
4. Incorrect Build Number
   • If old tags were deleted or forcibly rewritten, the count might shift. Usually keep tags forever to ensure a stable sequence.

---

1. How do I do a Major bump if I forget the label?

   • You can re-run the PR with the correct label or just push a new commit with the major label. Otherwise, it defaults to patch.

2. Why do we use rc.<N> on release/* branches?

   • This indicates a “release candidate.” Each new commit increments <N> by counting commits on that branch or from develop. Merging to main finalizes the version.

3. Can I override the build number manually?

   • Not in the default script. If you want, you can add a step to read an input or do extra logic, but the default approach is purely tag-count-based.

4. What if I want to skip GPG signing in the main repo?

   • You can adjust or remove the GPG logic. Currently, it’s only disabled for forks.

5. If I run workflow_dispatch manually, how do I do a major or minor bump?

   • The default script sets patch if no label is found. If you want a UI prompt or different logic, you can edit the “Determine bump type” step to read an input.

With these guidelines, you have a clear path for using, maintaining, and debugging the Build VI Package workflow for LabVIEW Icon Editor.