Version Pinning

BugDrop supports version-aware URLs so you can control how a deployed widget is updated. The unversioned URL follows the current deployment. Major and minor aliases move only when an operator completes an on-demand release. An exact URL can identify an asset in the current deployment when it is present in the authoritative versions.json, but availability is not guaranteed across later releases.

Recommended Setup

The installation guide uses the currently available widget.v1.56.4.js asset so you can test a specific version before updating:

<script
  src="https://bugdrop.neonwatty.workers.dev/widget.v1.56.4.js"
  data-repo="owner/repo"
></script>

Use the same URL in each example you copy. An exact URL controls which asset you request; it does not guarantee permanent hosting. Confirm availability before deployment and review the limits below before relying on it for long-term reproducibility.

For automatic updates, use https://bugdrop.neonwatty.workers.dev/widget.js. That URL follows the current hosted deployment. Major and minor aliases offer narrower update policies when the corresponding assets are available.

Version URL Reference

BugDrop follows semantic versioning (major.minor.patch). You can pin to any level of specificity:

Major Version Alias (Automatic Updates)

<script
  src="https://bugdrop.neonwatty.workers.dev/widget.v1.js"
  data-repo="owner/repo"
></script>

This loads the latest 1.x.x release. You get bug fixes and new features automatically, with the intention of preserving compatibility. Choose this when you want automatic updates within a major version:

• You get bug fixes automatically -- No action needed when patches are released
• You get new features -- Minor version updates add functionality without breaking existing behavior
• You choose major upgrades -- Major version bumps require you to explicitly update the URL. Test updates against your integration; version numbering is not a guarantee against regressions

Minor Version Pin

<script
  src="https://bugdrop.neonwatty.workers.dev/widget.v1.1.js"
  data-repo="owner/repo"
></script>

This loads the latest 1.1.x release. You only get patch updates (bug fixes and security patches). New features from minor versions are not included until you manually update the URL. Use this if you want maximum stability while still receiving critical fixes.

Exact Version Pin

<script
  src="https://bugdrop.neonwatty.workers.dev/widget.v1.1.0.js"
  data-repo="owner/repo"
></script>

This requests version 1.1.0 from the current deployment. Confirm that its filename and digest appear in the live versions.json before using it. The repository supports prospective retention from an explicitly bootstrapped boundary, but no production boundary or live N/N+1 durability has yet been proved. Until that separate operator proof, the manifest authenticates only what is deployed now. Historical bytes that are absent from the current deployment and GitHub Release assets are unavailable and must not be reconstructed or promised.

After a future authenticated bootstrap publication, a v2 manifest will declare the immutable boundary and supported exact set. Code rollback after that point must remain retention-aware; it may not discard the boundary or supported files. The repository's offline N/N+1 tests do not themselves prove that any production exact URL is durable.

How Versioned URLs Work

When an operator completes a release, the guarded build creates the new exact file and the aliases for that release:

• widget.js -- Always points to the latest version
• widget.v1.js -- Points to the latest 1.x.x version
• widget.v1.1.js -- Points to the latest 1.1.x version
• widget.v1.1.0.js -- Names the 1.1.0 asset when that file is deployed

The deployed versions.json is authoritative for which assets exist in the current deployment and which version each alias currently selects. It is not a cross-release archive. GitHub Releases are the canonical release record and carry the authenticated assets attached at publication. A source tag, changelog entry, or prior manifest alone does not prove that a static URL remains available.

Choosing the Right Pin Level

Here is a decision guide:

Use /widget.js (no pin) when:

• You are in active development
• You are testing the widget locally
• You want to always have the latest features and fixes
• You are comfortable with occasional behavior changes

Use /widget.v1.js (major pin) when:

• You are running a production site
• You want automatic bug fixes and new features
• You want protection from breaking API changes
• You will test your integration after updates

Use /widget.v1.1.js (minor pin) when:

• You want only bug fixes, not new features
• You have specific behavior you depend on and want to avoid any UI changes
• You prefer to manually opt in to new features

Use /widget.v1.1.0.js (exact URL) when:

• You are inspecting or validating an asset present in the current deployment
• You have verified its filename and digest against the live versions.json
• You want to choose when to update, and will verify the URL remains available

For long-term reproducibility, keep an independently controlled copy of an authenticated release asset. An exact URL available today does not by itself establish a cross-release hosting guarantee.

Upgrading Versions

To upgrade from one version to another, simply change the URL in your script tag:

<!-- Before: pinned to v1 -->
<script src="https://bugdrop.neonwatty.workers.dev/widget.v1.js" ...></script>

<!-- After: upgrading to v2 -->
<script src="https://bugdrop.neonwatty.workers.dev/widget.v2.js" ...></script>

Before upgrading, check the corresponding GitHub Release for canonical notes and assets. The changelog is an incomplete historical aid.

Checking Your Current Version

You can check which version of BugDrop is loaded by opening your browser's developer console and typing:

console.log(window.BugDrop);

The widget version is also included in the console log message when the widget initializes. To verify an exact URL in the current deployment, compare its filename and digest with the live versions.json.

Next Steps

• View GitHub Releases for canonical release history
• Configure the widget with data attributes
• Test your setup with Playwright