Principle: Semantic versioning and API contracts

Without clear versioning, library updates break dependent code unexpectedly.

Semantic versioning (SemVer) rules:

MAJOR.MINOR.PATCH  (e.g., 2.4.1)

MAJOR: Breaking changes (incompatible API changes)
  - Removing a public function
  - Changing function signature
  - Changing default behavior
  - Removing a config option
  - Changing data format

MINOR: New features (backward-compatible)
  - Adding a new function
  - Adding optional parameters
  - Adding new config options
  - Deprecating (not removing) features

PATCH: Bug fixes (backward-compatible)
  - Fixing incorrect behavior
  - Performance improvements (same API)
  - Security patches

Practical guidelines:

1. Pre-1.0 (0.x.y): Anything can change
   - API is unstable, use at your own risk
   - 0.1.0 -> 0.2.0 may break everything

2. Lock file strategy:
   - "^2.4.1" = allow 2.4.1 to 2.x.x (trust minor/patch)
   - "~2.4.1" = allow 2.4.1 to 2.4.x (trust patch only)
   - "2.4.1"  = exact version (most conservative)
   - Always use a lock file (package-lock.json, Pipfile.lock)

3. When you make breaking changes:
   - Increment MAJOR
   - Document migration path
   - Consider a deprecation period in previous MINOR
   - Provide codemod tools for large-scale changes

4. What's NOT a breaking change:
   - Adding a new optional parameter with default
   - Adding new types/classes
   - Widening accepted input types
   - Bug fix that changes incorrect behavior
     (debatable - some users depend on bugs)

For internal APIs: Even if you don't publish a library, version your internal APIs. Breaking changes should be communicated and coordinated.

SemVer communicates intent. Users know that minor/patch updates are safe, and major updates require attention. Without it, every update is a gamble.

Library and API versioning