TwitterProduct HuntLinkedInGitHubJumboGet Started
DocsContributingVersioning

Versioning

We follow Semantic Versioning (SemVer) for all our packages and APIs.

Version Format

MAJOR.MINOR.PATCH
# Example: 1.2.3
  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes (backward compatible)

Version Management

NPM Version

# Patch release
npm version patch
# 1.2.3 -> 1.2.4
 
# Minor release
npm version minor
# 1.2.3 -> 1.3.0
 
# Major release
npm version major
# 1.2.3 -> 2.0.0

Git Tags

# Create annotated tag
git tag -a v1.2.3 -m "Version 1.2.3"
 
# Push tags
git push origin --tags

Release Process

  1. Update Version

    # Update package.json
npm version minor
 
# Update changelog
git cliff -o CHANGELOG.md
 
# Commit changes
git add CHANGELOG.md
git commit -m "chore: update changelog"

  2. Create Release

    # Create GitHub release
gh release create v1.2.3 \
  --title "Version 1.2.3" \
  --notes-file CHANGELOG.md

API Versioning

URL Versioning

# Current version
https://api.lomi.africa/v1/checkout/sessions
 
# Future version
https://api.lomi.africa/v2/checkout/sessions

Version Lifecycle

  1. Active

    • Latest version
    • Full support
    • Regular updates

  2. Maintained

    • Previous version
    • Security updates
    • Bug fixes only

  3. Deprecated

    • Old version
    • Limited support
    • Migration required

Breaking Changes

  1. Notification

    • Advance notice (minimum 6 months)
    • Migration guide
    • Deprecation warnings

  2. Documentation

    • Version comparison
    • Migration steps
    • Code examples

  3. Support

    • Migration assistance
    • Legacy version support
    • Transition period

Version Control

Package Files

{
  "name": "@lomi/sdk",
  "version": "1.2.3",
  "engines": {
    "node": ">=14"
  }
}

Lock Files

# NPM
package-lock.json
 
# Yarn
yarn.lock

Best Practices

  1. Version Numbers

    • Use semantic versioning
    • Document changes
    • Keep changelog updated

  2. Dependencies

    • Pin exact versions
    • Regular updates
    • Security audits

  3. Release Notes

    • Clear descriptions
    • Breaking changes
    • Upgrade guide

Next Steps

BranchingBest Practices