Versioning
InstallHub uses Semantic Versioning (SemVer) for both packages and individual artifacts. Version numbers communicate the nature of changes to consumers — breaking, additive, or bug-fix.
SemVer Format
Both package versions and artifact versions follow the SemVer 2.0.0 specification: major.minor.patch
2.1.0
^ ^ ^
| | +-- Patch: bug fixes, no new features, backward compatible
| +----- Minor: new features, backward compatible
+-------- Major: breaking changesPackage-Level Versioning
The package version (in manifest.version) describes changes to the package as a whole. It is set by the package author at export time.
Major Version Bump — Breaking Changes
A major version bump signals that the package may not be backward compatible. Examples of breaking changes:
- A workflow node type was removed or renamed
- A required form field was added (existing data may fail validation)
- An entity schema field was removed or its data type changed
- A rule's condition language changed in an incompatible way
- A form action's payload structure changed
"allowMajorVersionUpgrade": true in ImportOptions.
Minor Version Bump — Additive Changes
A minor version bump adds new capabilities without breaking existing consumers:
- New optional form fields added
- New workflow branches or decision paths added
- New rules added (existing rules unchanged)
- New entity schema fields added (optional, nullable)
- README updated with new documentation
Patch Version Bump — Bug Fixes
A patch version bump fixes defects without adding functionality:
- Correcting a validation regex on a form field
- Fixing a typo in a rule condition
- Adjusting a timeout value in a workflow node
- Correcting label text on a form action button
Artifact-Level Versioning
Each artifact has its own version (in manifest.artifacts[].version). This tracks the individual artifact's evolution independently of the package version. An artifact version is set when the artifact is published in its source tenant.
When a package is re-exported with updated artifacts, the affected artifacts' versions should be bumped. The package version should also be bumped to reflect that the bundle's contents changed.
| Scenario | Artifact Version | Package Version |
|---|---|---|
| Form field label text corrected | Patch: 1.0.0 → 1.0.1 | Patch: 2.1.0 → 2.1.1 |
| New optional field added to form | Minor: 1.0.0 → 1.1.0 | Minor: 2.1.0 → 2.2.0 |
| Required field removed from form | Major: 1.0.0 → 2.0.0 | Major: 2.1.0 → 3.0.0 |
Version Uniqueness
Within a tenant, the combination of (packageName, version) must be unique. You cannot export two packages with the same name and version. To replace an existing package, you must increment the version.
On the marketplace (Phase 3), version uniqueness is enforced globally per publisher: a publisher cannot publish the same package name + version twice.
Pre-Release and Build Metadata
InstallHub supports SemVer pre-release identifiers for staging and testing purposes:
2.1.0-rc.1 // Release candidate
2.1.0-beta.3 // Beta release
2.1.0-alpha.1 // Alpha releasePre-release packages can be imported normally but are excluded from automatic update notifications on the marketplace. They are not eligible for Certified trust level.
0.x.x are considered unstable. Any version bump (including minor and patch) may include breaking changes. The import engine treats all 0.x.x packages as potentially breaking and always displays a warning.
Changelog Recommendation
For marketplace packages, it is strongly recommended to include a changelog in the README.md describing what changed in each version. This helps consumers make informed decisions about upgrades.
## Changelog
### 2.1.0 (2026-05-25)
- Added notification step after approval
- Added escalation path for overdue approvals
### 2.0.0 (2026-03-10)
- BREAKING: Removed legacy single-approver mode
- BREAKING: EmployeeForm now requires department field
- Added multi-approver support
### 1.3.0 (2025-11-20)
- Added optional notes field to EmployeeForm