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.

Default Behavior

The default script URL always loads the latest version of the widget:

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

This is fine for development and testing, but for production sites you may want more control over when updates are applied.

Version URL Reference

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

URL Example Update Behavior Best For
/widget.js Always latest Gets all updates automatically Development, testing
/widget.v1.js Major pin Gets minor and patch updates (1.x.x) Production (recommended)
/widget.v1.1.js Minor pin Gets patch updates only (1.1.x) Cautious production
/widget.v1.1.0.js Exact URL Identifies a listed current-deployment asset Inspection and validation

Major Version Pin (Recommended for Production)

<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, but never a breaking change. This is the recommended approach for production sites because:

  • 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 are protected from breaking changes -- Major version bumps (which may change the API or behavior) require you to explicitly update the URL

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
  • This is the recommended default for most production sites

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 do not depend on that URL remaining available after another release

Production cutover is blocked until a separately authorized operator phase establishes the boundary and proves live N/N+1 behavior. Until then, use a separately controlled archive if your application requires cross-release reproducibility.

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