External LibrariesDeploymentVersioning

Versioning Best Practices

Manage library versions effectively across environments.

Version Strategy

EnvironmentVersionURL Example
Development@latest...@latest/dist/build.umd.js
Staging@latest or specific...@1.2.0/dist/build.umd.js
ProductionSpecific version...@1.2.0/dist/build.umd.js

Development Workflow

Use @latest for Rapid Iteration

Library URL: https://unpkg.com/@your-org/test-lib@latest/dist/build.umd.js

Benefits:

  • Every npm publish takes effect immediately
  • No need to update ReAPI registration
  • Fast feedback loop

Pin Version Before Production

# When ready for production
npm version 1.0.0
npm publish

Update ReAPI:

Library URL: https://unpkg.com/@your-org/test-lib@1.0.0/dist/build.umd.js

Semantic Versioning

Follow semver for predictable updates:

Patch (1.0.0 → 1.0.1)

Bug fixes, no new features

npm version patch
# Update: Fix assertion message typo
# Update: Handle null values in generator

Minor (1.0.0 → 1.1.0)

New features, backward compatible

npm version minor
# Added: New "isValidIBAN" assertion
# Added: "generateOrder" value generator

Major (1.0.0 → 2.0.0)

Breaking changes

npm version major
# Breaking: Renamed "validateUser" to "isValidUser"
# Breaking: Changed generator parameter structure

Handling Breaking Changes

1. Communicate with QA

## Breaking Changes in v2.0.0
 
### Renamed Components
- `validateUser` → `isValidUser`
- `genUser` → `generateUser`
 
### Changed Parameters
- `generateOrder(count)` → `generateOrder({ count, currency })`
 
### Migration Steps
1. Update test flows using old component names
2. Update parameter configurations
3. Re-run affected tests

2. Deprecate Before Removing

// v1.x - Mark as deprecated
export const validateUser: AssertionFunction = {
  id: "validate-user",
  name: "Validate User",
  enabled: true,
  deprecated: true,  // Hidden from UI, still works
  function: async (value) => {
    // Call new implementation
    return isValidUser.function(value);
  },
};
 
// v2.x - New implementation
export const isValidUser: AssertionFunction = {
  id: "is-valid-user",
  name: "Is Valid User",
  enabled: true,
  deprecated: false,
  function: async (value) => {
    // New implementation
  },
};

3. Run Both Versions (Transition Period)

Project A (migrating):
  Library: @your-org/test-lib@1.5.0  # Old version

Project B (migrated):
  Library: @your-org/test-lib@2.0.0  # New version

Version Pinning in ReAPI

Single Version

https://unpkg.com/@your-org/test-lib@1.2.3/dist/build.umd.js

Pros:

  • Completely stable
  • No surprises

Cons:

  • Manual updates required

Version Range

https://unpkg.com/@your-org/test-lib@^1.2.0/dist/build.umd.js

Pros:

  • Auto-gets patch updates
  • Balance of stability and updates

Cons:

  • Potential for unexpected changes

Latest (Development Only)

https://unpkg.com/@your-org/test-lib@latest/dist/build.umd.js

Pros:

  • Always current
  • Fast iteration

Cons:

  • Can break tests unexpectedly
  • Not for production

Update Process

1. Develop and Test Locally

npm run dev
npm test

2. Publish New Version

npm version patch  # or minor/major
npm publish

3. Update Staging

  1. Change library URL in staging project
  2. Click Sync from URL
  3. Run test suite

4. Update Production

  1. Verify staging passed
  2. Change library URL in production project
  3. Click Sync from URL
  4. Monitor test results

Rollback

If a new version causes issues:

Quick Rollback

Change URL back to previous version:

# Before (broken)
https://unpkg.com/@your-org/test-lib@1.2.0/dist/build.umd.js

# After (working)
https://unpkg.com/@your-org/test-lib@1.1.0/dist/build.umd.js

Click Sync from URL to restore previous components.

Republish Fix

# Fix the issue
git revert HEAD
npm version patch
npm publish

Changelog

Maintain a changelog for version tracking:

# Changelog
 
## [1.2.0] - 2024-01-20
### Added
- `isValidIBAN` assertion
- `generatePayment` value generator
 
### Fixed
- `isValidEmail` now handles plus signs
 
## [1.1.0] - 2024-01-15
### Added
- `auth-signature` API hook
 
## [1.0.0] - 2024-01-01
### Initial Release
- Core assertions
- Basic generators
- Auth hooks
ReAPI CLI SyncRegistration & Sync