Overview

Document versioning keeps a complete history of every change to your important files. When you update a procedure, fix a typo, or revise a policy, CalmCompliance creates a new version while preserving the old one. This means you can see exactly what changed, when it changed, and who changed it—essential for compliance auditing and maintaining institutional knowledge.

Users always see the current published version by default, but you can access the full version history whenever needed.

Before You Start

To add new versions to documents, you'll need the Manager role for the Documents module. If you can't see the Upload New Version button on a document, ask your site administrator to update your permissions in Settings > User Management > Edit Access.

Understanding Version Numbers

CalmCompliance uses semantic versioning with two types of updates:

Minor versions (e.g., 1.0 → 1.1): Small changes, corrections, or clarifications that don't fundamentally change the document
Major versions (e.g., 1.1 → 2.0): Significant updates, policy changes, or complete rewrites

When you upload the first document, it starts at version 1.0. Each subsequent update increments either the major or minor version number based on the scope of your changes.

Adding a New Version

Open the document you want to update
Click Upload New Version (usually found in the document actions menu)
Choose the version type:
- Minor Version: For small changes (e.g., 1.0 → 1.1)
- Major Version: For significant changes (e.g., 1.0 → 2.0)
- Draft: To work on changes privately before publishing
Click Choose File and select your updated PDF
Add a Change Description (required for published versions): Explain what changed so others understand the update
Click Upload

The new version immediately becomes the current version that users see. The previous version remains in the document's history.

Working with Draft Versions

Draft versions let you prepare updates without immediately publishing them. This is useful when:

You need to review changes with colleagues before going live
The document requires approval before publishing
You're making incremental updates over several days

Creating a Draft

When uploading a new version, select Draft as the version type
Upload your updated file
No change description is required yet—you can add it when you publish
Click Upload

The draft version is saved but doesn't become the current version. Only users with Manager or Admin roles can see that a draft exists.

Publishing a Draft

Open the document with a draft version
You'll see a Publish Draft section
Choose whether this is a Minor or Major version update
Add a Change Description (required): Explain what changed
Click Publish

If the document has an approval workflow, clicking Publish triggers the approval process instead of immediately publishing. Once approved, the draft becomes the current version.

Viewing Version History

Open any document
Look for the Versions tab or Version History section
You'll see a list of all published versions with:
- Version number
- Upload date
- Who uploaded it
- Change description

Click any version to view that specific revision. This is useful for understanding how a document evolved or retrieving previous policy language.

Common Questions

What happens to the old version when I upload a new one?

Nothing is deleted. The old version remains in the version history. Users see the new version by default, but you can always access previous versions if needed.

Should I choose minor or major for most updates?

Use minor versions for corrections, clarifications, or small updates. Use major versions when the changes are significant enough that users should be aware something important changed—for example, a new safety requirement or updated procedure.

Can I delete a version after uploading?

No, version history is permanent to maintain a complete audit trail. If you uploaded the wrong file, simply upload another version immediately with the correct file.

Do users get notified when I publish a new version?

Users who are following the document receive a notification about the new version. If the document is distributed to users for acknowledgment, they'll need to re-acknowledge the updated version.

Can I upload a new version if a draft already exists?

No, you can only have one draft at a time. You must either publish or discard the existing draft before creating a new one.

What if I upload a new version but it needs approval?

If the document has an approval workflow assigned, new versions automatically follow that workflow. Upload the new version, and it will be sent to the designated approvers. The new version won't become current until it's approved.

How do I know which version users are currently seeing?

The document detail page shows the Current Version at the top. This is what users see when they open the document. If a draft exists, you'll see a separate Draft Version indicator visible only to Managers and Admins.

Best Practices

Write Clear Change Descriptions

Good change descriptions help users understand what changed without needing to read the entire document again:

✅ "Updated emergency contact numbers for facilities team"
✅ "Added new section 4.2 on remote work safety requirements"
❌ "Updates"
❌ "New version"

Use Drafts for Collaborative Review

If you need feedback before publishing, create a draft version and share the document link with reviewers. They can comment on the draft, and you can incorporate feedback before publishing.

Increment Major Versions Sparingly

Frequent major version jumps (1.0 → 2.0 → 3.0) can make users feel overwhelmed by change. Reserve major versions for truly significant updates. Most routine updates should be minor versions.

Document Versioning