Skip to content

VERSIONING.md

Jump to bottom
CeloHT edited this page Aug 10, 2026 · 1 revision

CeloHT Versioning

Document Type: Versioning Policy
Project: CeloHT
Status: Active / Evolving
Last Updated: August 2026
Authors: Johnny Dubic & CeloHT Community

1. Overview

This document defines how CeloHT versions software, applications, APIs, documentation, smart contracts, and other technical components.

A consistent versioning strategy helps users and contributors understand:

  • What changed

  • Whether an update is compatible

  • Whether migration is required

  • Which version is supported

  • When a release was published

2. Versioning Principles

CeloHT follows these principles:

  • Predictability

  • Traceability

  • Compatibility awareness

  • Reproducibility

  • Clear release communication

  • Security-conscious upgrades

3. Semantic Versioning

Where appropriate, CeloHT software follows Semantic Versioning:

MAJOR.MINOR.PATCH

Example:

2.4.1

Where:

  • 2 = major version

  • 4 = minor version

  • 1 = patch version

4. MAJOR Versions

A major version indicates potentially breaking changes.

Example:

1.x.x → 2.0.0

Possible reasons include:

  • Breaking API changes

  • Removal of supported functionality

  • Major architecture changes

  • Incompatible configuration changes

  • Significant contract-interface changes

Major releases should include migration guidance where required.

5. MINOR Versions

A minor version generally introduces backward-compatible functionality.

Example:

2.3.0 → 2.4.0

Examples:

  • New features

  • New optional API endpoints

  • New user functionality

  • New integrations

  • Performance improvements that preserve compatibility

6. PATCH Versions

A patch version generally contains backward-compatible fixes.

Example:

2.4.1 → 2.4.2

Examples:

  • Bug fixes

  • Security fixes

  • Documentation corrections

  • Small implementation improvements

Security patches should be prioritized appropriately.

7. Pre-Releases

Pre-release versions may be used for software that is not yet considered stable.

Examples:

2.0.0-alpha.1
2.0.0-beta.1
2.0.0-rc.1

Alpha

Early development and experimentation.

Beta

Feature-complete or substantially complete testing version.

Release Candidate

A candidate considered ready for production if no blocking issues are found.

8. Development Versions

Development builds may use identifiers such as:

2.5.0-dev

Development versions should not automatically be considered production-ready.

9. Git Tags

Released versions should be associated with Git tags where practical.

Example:

git tag v2.4.1
git push origin v2.4.1

Tags should point to the exact commit corresponding to the release.

10. Release Notes

Each significant release should provide release notes.

Release notes should summarize:

  • New features

  • Improvements

  • Fixes

  • Security changes

  • Breaking changes

  • Migration requirements

11. Changelog

CeloHT should maintain a changelog for material changes.

A changelog helps users understand project evolution without examining every commit.

See:

CHANGELOG.md

12. Version Sources

A project should avoid maintaining conflicting version numbers across multiple locations.

Where possible, the authoritative version should be defined in the project's package or release configuration.

Other displayed versions should derive from that source.

13. Package Versioning

JavaScript/TypeScript packages may define versions through package.json.

Example:

{
  "version": "2.4.1"
}

The actual project structure may differ.

14. API Versioning

Public APIs may require independent versioning.

Common approaches include:

/api/v1/

and:

/api/v2/

Breaking API changes should not be introduced without appropriate communication.

15. API Compatibility

When possible, existing API clients should continue working after non-breaking releases.

Breaking changes should provide:

  • Migration documentation

  • Deprecation notice

  • New endpoint or version

  • Appropriate transition period where practical

16. Deprecation

A feature may be marked deprecated before removal.

Deprecation communication should explain:

  • What is deprecated

  • Why

  • Replacement

  • Expected removal timeline

  • Migration instructions

17. Removal

Removing a public feature should generally require:

  1. Deprecation

  2. Communication

  3. Migration guidance

  4. Release documentation

Security-critical circumstances may require faster removal.

18. Smart Contract Versioning

Smart contracts require special treatment because deployed blockchain code may be difficult or impossible to modify.

A contract version should identify:

  • Source version

  • Deployment

  • Network

  • Contract address

  • Configuration

  • Interface

Example:

Celo Mainnet
Contract: ExampleContract
Version: 1.2.0
Address: 0x...

19. Immutable Contracts

If a smart contract cannot be upgraded, deploying a new version may require a new address.

Users should never assume that a new contract deployment automatically replaces the previous one.

20. Upgradeable Contracts

If an upgradeable architecture is used, the upgrade mechanism should be documented.

Documentation should identify:

  • Upgrade authority

  • Upgrade mechanism

  • Governance requirements

  • Proxy architecture

  • Security controls

21. Contract Interface Compatibility

Changes to a smart contract interface should be treated carefully.

Potentially breaking changes include:

  • Removing functions

  • Changing function parameters

  • Changing return types

  • Changing expected behavior

  • Altering authorization requirements

22. Database Versioning

Database schema changes should be tracked through migrations.

A migration should be:

  • Versioned

  • Reviewable

  • Reproducible

  • Tested

Production migrations should have appropriate rollback or recovery planning when feasible.

23. Configuration Versioning

Configuration changes that affect application behavior should be documented.

Sensitive configuration values must never be committed to public repositories.

24. Documentation Versioning

Documentation should identify important version-specific instructions when necessary.

For example:

Applies to: CeloHT Platform v2.x

This prevents users from applying obsolete instructions to newer systems.

25. SDK Versioning

An SDK should follow predictable versioning so developers can understand compatibility.

Example:

@celoht/sdk 1.5.0

Breaking SDK changes should generally trigger a major version.

26. Mobile Application Versions

If CeloHT provides mobile applications, versions should be visible to users.

A release should identify:

  • Application version

  • Build number where relevant

  • Release date

  • Supported platform

  • Major changes

27. Web Application Versions

Web applications may display or expose a release identifier for troubleshooting.

Example:

CeloHT Web v2.4.1

This helps support teams reproduce reported issues.

28. Build Numbers

Build numbers may be used alongside semantic versions.

Example:

Version: 2.4.1
Build: 184

Build numbers should generally increase monotonically within the relevant release system.

29. Git Commit References

For technical troubleshooting, releases may reference:

  • Git commit SHA

  • Git tag

  • Build identifier

This allows developers to identify the exact source used to produce a deployment.

30. Release Branches

Projects may use branches such as:

main
develop
release/*
hotfix/*

The exact branching model should be defined by the repository's contribution and release procedures.

31. Hotfixes

A hotfix is an urgent change addressing a serious production issue.

Typical flow:

Production Issue
      ↓
Investigate
      ↓
Create Hotfix
      ↓
Test
      ↓
Review
      ↓
Release
      ↓
Monitor

32. Security Releases

Security releases should receive appropriate priority.

Release notes should communicate the security impact without unnecessarily exposing exploit details before users have an opportunity to update.

33. Emergency Releases

Critical incidents may require an emergency release outside the normal release schedule.

Emergency releases should still be:

  • Tested

  • Reviewed

  • Documented

  • Tracked

34. Release Compatibility

Before publishing a release, maintainers should evaluate:

  • Application compatibility

  • API compatibility

  • Database compatibility

  • Wallet compatibility

  • Smart-contract compatibility

  • Infrastructure compatibility

35. Migration Guides

Breaking changes should include migration instructions.

A migration guide should explain:

Current Version
      ↓
Required Changes
      ↓
Migration Steps
      ↓
Testing
      ↓
New Version

36. Version Support

CeloHT may define support periods for important releases.

Support levels can include:

  • Current

  • Maintained

  • Security-only

  • Deprecated

  • End-of-life

37. End of Life

When a version reaches end-of-life:

  • New feature development stops.

  • Regular bug fixes stop.

  • Security support may stop according to the published policy.

  • Users should migrate to a supported version.

38. Version Matrix

For complex systems, CeloHT may maintain a compatibility matrix.

Example:

Component | Version | Status -- | -- | -- Platform | 2.x | Current SDK | 1.x | Supported API | v1 | Maintained Contract | 1.x | Deployed Documentation | Current | Active

The actual matrix should be maintained according to the current project state.

39. Release Verification

Before declaring a release stable, maintainers should verify:

  • Build succeeds

  • Tests pass

  • Security checks pass

  • Documentation is updated

  • Version number is correct

  • Release artifacts are reproducible where practical

40. Release Artifacts

A release may include:

  • Source code

  • Packages

  • Container images

  • Deployment artifacts

  • Documentation

  • Checksums

  • Release notes

41. Checksums and Integrity

Where appropriate, release artifacts may include cryptographic checksums.

This allows users to verify that downloaded files have not been altered.

42. Reproducible Releases

CeloHT should aim for reproducible builds where practical.

A reproducible build allows independent parties to verify that the published artifact corresponds to the documented source.

43. Versioning and Governance

Material versioning-policy changes should follow applicable project governance procedures.

Technical maintainers should not use version numbers to bypass governance requirements.

44. Versioning and Documentation

Whenever a version introduces meaningful behavior changes, related documentation should be reviewed.

Affected documents may include:

  • README.md

  • QUICK_START.md

  • USER_GUIDE.md

  • TUTORIALS.md

  • SDK.md

  • API documentation

  • SECURITY.md

45. Versioning and Testing

Every release should use the appropriate testing strategy.

Testing may include:

  • Unit tests

  • Integration tests

  • End-to-end tests

  • Contract tests

  • Security tests

  • Performance tests

See:

TESTING.md

46. Versioning and Performance

Performance-sensitive releases should document material performance changes when measured.

Claims should be supported by reproducible measurements where possible.

See:

PERFORMANCE.md

47. Versioning and Transparency

CeloHT should avoid silently replacing major behavior while keeping the same version identifier.

Version numbers should communicate meaningful changes.

48. Version Naming

Release names may be used for communication, but they should not replace technical version identifiers.

Example:

CeloHT "Community Release"
v2.4.0

The semantic version remains the authoritative technical identifier.

49. Version History

Historical versions should remain traceable through:

  • Git history

  • Git tags

  • Release pages

  • Changelog

  • Archived documentation where appropriate

50. Maintaining This Policy

This policy should evolve as CeloHT's technology grows.

Changes should account for:

  • New applications

  • New APIs

  • New smart contracts

  • New SDKs

  • New infrastructure

  • Security requirements

51. Final Statement

A clear versioning system makes software easier to understand, maintain, secure, and trust.

CeloHT uses versioning to make technical evolution visible and predictable.

The guiding principle is:

Every meaningful release should be identifiable, traceable, documented, and understandable.

Document Status: Active / Evolving
Maintained By: CeloHT Community
Primary Authors: Johnny Dubic & CeloHT Community
Versioning Standard: Semantic Versioning where applicable

© 2026 CeloHT - Open Source. Global Impact. Licensed under Apache.

CeloHT

Community-powered Web3 for real-world impact.

CeloHT is an open-source community initiative building practical solutions around Web3, financial inclusion, education, decentralized services, and environmental impact.

Learn. Build. Participate. Impact.

Clone this wiki locally