Versioning Guide
How documentation versions are managed and tied to Smartflow product releases.
Version Strategy
Documentation versions correspond to Smartflow product versions. When a new product version ships, a documentation snapshot is created.
| Product Version | Docs Version | Date | Status |
|---|---|---|---|
| v1.0 | current | 2026-03-25 | Active (latest) |
Creating a New Version
When a new product version is ready for release:
- Ensure all docs for the release are merged to
main. - Run the versioning command from the
site/directory:
cd site
npm run version <version-number>
Example:
npm run version 1.1
This creates:
site/versioned_docs/version-1.1/— snapshot of../02-user-docs/at this point.site/versioned_sidebars/version-1.1-sidebars.json— sidebar snapshot.- Updates
site/versions.jsonto include the new version.
- Update
docusaurus.config.tsto set the new version label if needed.
Version Lifecycle
| State | Description |
|---|---|
| Current | The latest version, actively maintained. Maps to main branch docs. |
| Maintained | Previous major version still receiving updates for critical fixes. |
| Archived | Old version, read-only. Banner shown to readers suggesting they switch to current. |
Changelog Requirements
Every version must have a corresponding entry in the release notes folder (02-user-docs/release-notes/).
Each release note must include:
- Version number and date.
- New features with descriptions.
- Improvements and fixes.
- Breaking changes (if any).
- Known issues.
Version Dropdown
The Docusaurus navbar includes a version dropdown (configured for the /docs portal only). Users can switch between versions to view documentation for their deployed Smartflow version.
What Gets Versioned
| Content | Versioned? | Reason |
|---|---|---|
User Docs (/docs) | ✅ Yes | Content changes with product features |
Partner Hub (/partners) | ❌ No | Collateral is version-agnostic |
Internal (/internal) | ❌ No | Specs and support evolve continuously |