Blog Twitter Facebook Product Hunt LinkedIn GitHub Jumbo
DocsContributingVersioning

Versioning

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

Version format

SemVer 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

Terminal - 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

Terminal - git tag
# 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

    Terminal - 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

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

API versioning

URL versioning

API URL Versioning Example
# 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

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

Lock files

Lockfile Examples
# 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