Semantic Versioning Commitment

Introduction

LARC is committed to Semantic Versioning 2.0.0 (SemVer) for all packages in the LARC ecosystem. This document outlines our versioning policy, what constitutes breaking changes, and our commitment to API stability.

Version Format

All LARC packages follow the SemVer format: MAJOR.MINOR.PATCH

1.2.3
│ │ └─ PATCH version (bug fixes, no API changes)
│ └─── MINOR version (new features, backward compatible)
└───── MAJOR version (breaking changes, not backward compatible)

Examples

• 1.0.0 → 1.0.1 - Bug fix (safe to update)
• 1.0.0 → 1.1.0 - New feature (safe to update)
• 1.0.0 → 2.0.0 - Breaking change (review MIGRATION.md before updating)

Version Increment Rules

PATCH Version (x.x.X)

• ✅ No API changes
• ✅ 100% backward compatible
• ✅ No behavioral changes (except bug fixes)
• ✅ Safe to update without code changes

// All of these are PATCH updates:
// - Fix message delivery race condition
// - Improve autoloader performance
// - Fix memory leak in subscription cleanup
// - Update documentation typos
// - Add JSDoc comments

• New public methods or properties
• New component attributes
• New event types
• Deprecation warnings

MINOR Version (x.X.x)

• ✅ Backward compatible
• ✅ Existing code continues to work
• ✅ New features are opt-in
• ⚠️ May add deprecation warnings

// All of these are MINOR updates:
// - Add new component: <pan-wizard>
// - Add new PanBus configuration option
// - Add new PanClient convenience method
// - Add new autoloader configuration option
// - Deprecate old API (but keep it working)
// - Add new event type
// - Add new attribute to existing component

• New capabilities available
• Existing code needs no changes
• Deprecation warnings may appear in console
• Review release notes for new features

MAJOR Version (X.x.x)

• ⚠️ Breaking changes present
• ⚠️ Code changes likely required
• ⚠️ Thorough testing recommended
• ✅ MIGRATION.md provided

// All of these are MAJOR updates:
// - Remove deprecated API
// - Change component attribute name
// - Change message format
// - Change event detail structure
// - Change autoloader behavior
// - Rename exported classes
// - Change method signatures
// - Change default configuration values

What Constitutes a Breaking Change

⚠️ Breaking Changes (Require MAJOR version bump)

#### 1. Public API Changes

// BREAKING: Renamed method
class PanClient {
  // v1.x
  subscribe(topics, handler) { }

  // v2.x
  on(topics, handler) { } // BREAKING: different name
}

// BREAKING: Changed method signature
class PanClient {
  // v1.x
  publish(msg) { }

  // v2.x
  publish(topic, data, options) { } // BREAKING: different signature
}

// BREAKING: Removed method
class PanClient {
  // v1.x
  oldMethod() { }

  // v2.x - method removed // BREAKING
}

#### 2. Component Attribute Changes

<!-- BREAKING: Renamed attribute -->
<!-- v1.x -->
<pan-bus max-retained="1000"></pan-bus>

<!-- v2.x -->
<pan-bus max-messages="1000"></pan-bus> <!-- BREAKING -->

<!-- BREAKING: Changed attribute behavior -->
<!-- v1.x: debug="true" enables verbose logging -->
<pan-bus debug="true"></pan-bus>

<!-- v2.x: debug="verbose" required for same behavior -->
<pan-bus debug="verbose"></pan-bus> <!-- BREAKING -->

#### 3. Event Structure Changes

// BREAKING: Changed event detail structure
// v1.x
document.addEventListener('pan:deliver', (e) => {
  const { topic, data } = e.detail;
});

// v2.x
document.addEventListener('pan:deliver', (e) => {
  const { message } = e.detail; // BREAKING: nested differently
  const { topic, data } = message;
});

#### 4. Default Behavior Changes

// BREAKING: Changed default configuration
// v1.x: autoloader rootMargin defaults to 600px
window.panAutoload = { rootMargin: 600 };

// v2.x: defaults to 1200px - components load earlier
window.panAutoload = { rootMargin: 1200 }; // BREAKING: different timing

#### 5. Removed Features

// BREAKING: Removed configuration option
// v1.x
window.panAutoload = {
  legacyMode: true // supported
};

// v2.x - option removed // BREAKING

✅ Non-Breaking Changes (MINOR or PATCH)

#### 1. Adding New APIs

// NON-BREAKING: New method added
class PanClient {
  // v1.x
  publish(msg) { }
  subscribe(topics, handler) { }

  // v1.1: New method, old methods still work
  unsubscribeAll() { } // NON-BREAKING
}

#### 2. Adding New Attributes

<!-- NON-BREAKING: New optional attribute -->
<!-- v1.x -->
<pan-bus max-retained="1000"></pan-bus>

<!-- v1.1: New attribute, old ones still work -->
<pan-bus max-retained="1000" log-level="debug"></pan-bus>
<!-- NON-BREAKING -->

#### 3. Adding New Events

// NON-BREAKING: New event type
// v1.x: pan:deliver, pan:publish, pan:subscribe

// v1.1: New event, old events still work
document.addEventListener('pan:metrics', (e) => {
  // NON-BREAKING: new opt-in event
});

#### 4. Deprecations (with working code)

// NON-BREAKING: Deprecation warning, but method still works
class PanClient {
  // v1.1
  oldMethod() {
    console.warn('oldMethod() is deprecated, use newMethod()');
    return this.newMethod(); // still works!
  }
  newMethod() { } // new preferred method
}

#### 5. Bug Fixes

// NON-BREAKING: Bug fix that makes code work correctly
// v1.0.0: Message delivery sometimes failed (bug)
// v1.0.1: Fixed message delivery (patch)

#### 6. Performance Improvements

// NON-BREAKING: Same API, faster execution
// v1.0.0: Autoloader scans every 100ms
// v1.0.1: Autoloader uses IntersectionObserver (faster)

Pre-release Versions

Alpha Releases (x.x.x-alpha.N)

• ⚠️ No stability guarantees
• ⚠️ Breaking changes between alphas
• ⚠️ Not for production use

Beta Releases (x.x.x-beta.N)

• ⚠️ Limited stability
• ⚠️ API may change before final release
• ✅ Can be tested in non-critical production

Release Candidates (x.x.x-rc.N)

• ✅ API frozen (no changes unless critical bug)
• ✅ Production-ready quality
• ✅ Only critical bug fixes

Deprecation Policy

Deprecation Process

Example Timeline

// v1.0.0 - Current API
client.oldMethod();

// v1.5.0 - MINOR: Deprecation announced
client.oldMethod(); // works, shows console.warn()
client.newMethod(); // recommended new API

// v2.0.0 - MAJOR: Old API removed
// client.oldMethod(); // ❌ ERROR: removed
client.newMethod(); // ✅ only option

Minimum Deprecation Period

• Public API: 1 MAJOR version or 6 months, whichever is longer
• Component Attributes: 1 MAJOR version or 6 months
• Events: 1 MAJOR version or 6 months
• Configuration Options: 1 MAJOR version or 6 months

Package-Specific Versioning

@larcjs/core

• MAJOR changes are rare (≤1 per year)
• MINOR releases every 2-3 months
• PATCH releases as needed (bug fixes)

• PAN bus message format is stable
• Core events (pan:publish, pan:deliver, etc.) are stable
• Autoloader API is stable

@larcjs/ui

• MAJOR changes possible (new component architecture)
• MINOR releases monthly (new components, features)
• PATCH releases as needed

• Component tag names are stable once released
• Core attributes are stable (may add new ones)
• Events are stable (may add new ones)

Version Compatibility Matrix

Core Package Compatibility

| @larcjs/core | @larcjs/ui | Supported | |--------------|------------|-----------| | 1.x.x | 1.x.x | ✅ Fully compatible | | 1.x.x | 2.x.x | ⚠️ Check compatibility notes | | 2.x.x | 1.x.x | ⚠️ May have issues | | 2.x.x | 2.x.x | ✅ Fully compatible |

Browser Support Policy

• Current Major: Support last 2 years of browsers
• Previous Major: Support last 3 years at release time
• Dropping browser support: Requires MAJOR version bump

Release Schedule

Regular Release Cadence

• PATCH: As needed (bug fixes)
• MINOR: Every 2-3 months (new features)
• MAJOR: ~1 per year (breaking changes)

Security Releases

• Critical security issues: Emergency PATCH release within 48 hours
• Important security issues: PATCH release within 1 week
• Minor security issues: Next scheduled PATCH release

Guarantees and Commitments

What We Guarantee

What We Don't Guarantee

Migration Support

For MAJOR Version Updates

• 📖 Detailed MIGRATION.md guide
• 📋 Breaking changes checklist
• 💻 Code examples (before/after)
• ⚙️ Automated migration tools (when possible)
• 🆘 Migration support in GitHub Discussions

Reporting Versioning Issues

If You Encounter Issues

If you believe a release violates SemVer:

• Investigate within 48 hours
• Issue hotfix if confirmed violation
• Update documentation if needed
• Improve our process to prevent recurrence

Staying Informed

Release Notifications

• GitHub Releases: Full changelog + notes
• npm: Automatic notifications
• Breaking Changes: Prominently marked in CHANGELOG.md
• Security: GitHub Security Advisories

Best Practices

// package.json - Use tilde for PATCH updates only
{
  "dependencies": {
    "@larcjs/core": "~1.0.0" // ≥1.0.0 <1.1.0 (PATCH only)
  }
}

// package.json - Use caret for MINOR updates
{
  "dependencies": {
    "@larcjs/core": "^1.0.0" // ≥1.0.0 <2.0.0 (MINOR + PATCH)
  }
}

// package.json - Pin exact version for critical production
{
  "dependencies": {
    "@larcjs/core": "1.0.0" // exact version
  }
}

Version History

| Document Version | Date | Changes | |-----------------|------|---------| | 1.0 | Nov 24, 2024 | Initial semantic versioning commitment |

Questions?

• 📖 Documentation: https://larcjs.com/
• 💬 Discussions: https://github.com/larcjs/core/discussions
• 🐛 Issues: https://github.com/larcjs/core/issues