title	Versioning System

import NavContainer from '@site/src/components/NavContainer'; import DocTabs from '@site/src/components/DocTabs'; import TableVerticalNoRef from '@site/src/components/TableVerticalNoRef';

Versioning System

The RMC Software Documentation site uses a structured versioning system to maintain clarity and transparency as documentation evolves. This system helps both contributors and readers track significant updates to documentation over time.

Version Format: Major.Minor

All documentation versions follow a Major.Minor structure (e.g., v1.0, v1.1, v2.0).

When to Create a New Version

Major Version (X.0)

Create a new major version when making significant changes:

Indicators for Major Version:

Adding or removing entire chapters
Major restructuring of document organization
Updating documentation for new software major release
Substantial rewrites affecting multiple chapters
Significant changes to document scope or audience

Examples:

v1.0 → v2.0: Software updated from version 1.x to 2.x with new features
v1.0 → v2.0: Added three new chapters covering new functionality
v1.0 → v2.0: Completely restructured user guide organization

Minor Version (X.Y)

Create a new minor version for targeted updates:

Indicators for Minor Version:

Expanding existing sections with new material
Rewriting sections for improved clarity
Adding new subsections or examples to existing chapters
Updating screenshots or figures for minor software updates
Adding new procedures or workflows

Examples:

v1.0 → v1.1: Updated Chapter 3 with expanded troubleshooting section
v1.1 → v1.2: Added new examples to installation guide
v1.2 → v1.3: Rewrote data import procedures for clarity

Updates Without New Version

Some changes don't require a new version:

No Version Change Needed:

Fixing typos or grammatical errors
Correcting broken links
Formatting adjustments
Minor word changes for clarity
Updating contact information
Fixing image alignment or sizing

Key Principle: If the change doesn't affect the user's understanding or use of the software, it typically doesn't need a new version.

Version Folder Structure

Each version is stored in its own folder within the documentation structure:

docs/
└── software-name/
    ├── v1.0/              ← Version folder
    │   ├── 01-intro.mdx
    │   ├── 02-install.mdx
    │   └── 03-usage.mdx
    ├── v1.1/              ← New minor version
    │   ├── 01-intro.mdx
    │   ├── 02-install.mdx
    │   └── 03-usage.mdx   (updated content)
    └── v2.0/              ← New major version
        ├── 01-intro.mdx
        ├── 02-install.mdx
        ├── 03-usage.mdx
        └── 04-advanced.mdx  (new chapter)

Key Points:

Each version folder contains a complete copy of all documentation files
Users can switch between versions using the version selector
All versions remain accessible on the site
Older versions are preserved for users on older software versions

How to Create a New Version

Step 1: Determine Version Number

Decision Tree:

Is this a new document?
- Use v1.0 for the first version of a new document
Are you adding/removing chapters?
- Yes → Major version (e.g., v1.0 → v2.0)
- No → Continue to next question
Are you significantly rewriting multiple chapters?
- Yes → Major version
- No → Minor version (e.g., v1.0 → v1.1)

Step 2: Copy Existing Version Folder

Using Command Line:

# Copy most recent version to new version
cp -r docs/software-name/v1.0 docs/software-name/v1.1

# Windows PowerShell:
Copy-Item -Recurse docs/software-name/v1.0 docs/software-name/v1.1

Using File Explorer:

Navigate to docs/software-name/
Copy the most recent version folder (e.g., v1.0)
Paste and rename to new version (e.g., v1.1)

Step 3: Update Content in New Version

Make your changes in the new version folder only
Leave the old version folder unchanged
Update relevant files (chapters, images, etc.)

Example:

docs/
└── lifesim/
    ├── v1.0/              ← Don't touch
    │   └── 03-usage.mdx   (original content)
    └── v1.1/              ← Edit here
        └── 03-usage.mdx   (updated content)

Step 4: Copy Images/Assets to New Version Folder

Important: ALL images used in the new version must be placed in the new version's folder, even if they haven't changed from the previous version.

Create new version-specific folder:

static/
└── figures/
    └── software-name/
        ├── v1.0/      ← Old version images
        └── v1.1/      ← New version images (copy all from v1.0)

Copy all images from the previous version:

# Windows PowerShell:
Copy-Item -Recurse static/figures/software-name/v1.0 static/figures/software-name/v1.1

# Or using Command Line:
cp -r static/figures/software-name/v1.0 static/figures/software-name/v1.1

Add any new images to the new version folder
Remove any images no longer used in the new version
Update image paths in MDX files:
```
<Figure
  src="/figures/software-name/v1.1/screenshot.png"
  ...
/>
```
Note: Change the version number in ALL image paths, even for unchanged images.

Step 5: Copy and Update Bibliography

If your documentation uses citations and a bibliography:

Create new version-specific folder:

static/
└── bibliographies/
    └── software-name/
        ├── v1.0/
        │   └── bib.json
        └── v1.1/
            └── bib.json

Copy the bibliography from the previous version:

# Windows PowerShell:
Copy-Item -Recurse static/bibliographies/software-name/v1.0 static/bibliographies/software-name/v1.1

# Or using Command Line:
cp -r static/bibliographies/software-name/v1.0 static/bibliographies/software-name/v1.1

Update bib.json in the new version folder:
- If references haven't changed, no edits are needed
- If references were added, add the new entries to bib.json
- If references were removed, delete the entries from bib.json
Update bibliography path in MDX files:
```
<Bibliography bibFile="/bibliographies/software-name/v1.1/bib.json" />
```
Note: Change the version number in the bibliography path.

Step 6: Restart Development Server and Verify New Version

After creating a new version folder, restart the development server to trigger automatic version detection:

# Stop the server (if running)
Ctrl + C

# Start the server
npm start

What Happens Automatically:

Build scripts detect the new version folder
Version metadata is generated in static/versions/
Version selector dropdown is updated
Default version is set

:::info All necessary scripts run automatically during npm start or npm run build. You never need to run scripts manually. :::

Once the server is running, verify the new version:

Check Version Selector:
- Look for dropdown in top navigation
- Verify new version appears in list
- Click to switch between versions
Test Content:
- Browse new version pages
- Verify images load correctly
- Check all links work
- Test cross-references
- Verify bibliography displays correctly (if applicable)

Step 7: Commit Changes and Open a Pull Request

The main branch is protected — changes cannot be pushed directly. All revisions are committed to a feature branch and merged via a pull request. The branch prefix routes the PR to the appropriate review lane (see Review Lanes):

Major revision (e.g., v1.0 → v2.0): use prefix docs/major/
Minor revision (e.g., v1.0 → v1.1): use prefix docs/minor/

✅ Create a Branch

In GitHub Desktop, click the Current Branch dropdown
Click New Branch
Name the branch using the appropriate prefix (e.g., docs/minor/lifesim-users-guide-v1.1)
Confirm the branch is created from main
Click Create Branch

✅ Stage and Commit Changes

Changed files appear in the left sidebar under "Changes"
Review the changes in the diff viewer on the right
Enter a commit message in the Summary field (e.g., "Add v1.1 documentation with updated usage guide")
Optionally add a more detailed Description
Click Commit to docs/minor/...

✅ Push Changes and Open the PR

Click Publish branch (first push) or Push origin (subsequent pushes)
Click Create Pull Request — this opens the GitHub website to the PR creation page
Fill in the PR description, assign a peer reviewer if known, and click Create pull request

</> ), }, { label: 'Using Git (Command Line)', value: 'git', child: ( <>

✅ Create a Branch, Commit, and Push

{`# Create and switch to a new branch off main git checkout main git pull origin main git checkout -b docs/minor/lifesim-users-guide-v1.1 Stage and commit git add . git commit -m "Add v1.1 documentation with updated usage guide" Push the branch to GitHub

git push -u origin docs/minor/lifesim-users-guide-v1.1`}

Then open the PR on GitHub.com — the push output contains a link to "Create a pull request for this branch." Click it, fill in the description, and submit.

</> ), }, ]} defaultValue="github-desktop" />

After the PR is opened, a preview build is published to an unadvertised URL and the review workflow auto-assigns a lane label. See Author Workflow for what happens next.

Version Notice for Users

When a user visits an older version of a document, a version notice banner appears at the top of the page alerting them that a newer version is available.

How It Works:

Automatically detects the version from the page URL
Compares against latestVersions.json (auto-generated by scripts/versions.js)
If the current version is not the latest, a banner displays with a link to the latest version
The banner is rendered by the VersionNotice component inside NavContainer

Default Behavior:

Latest version is determined automatically from version folder names
Users reach different versions via direct URL links
No manual version selection dropdown is displayed

Best Practices

When to Version

DO create a new version when:

Software has a new release you're documenting
Making changes users need to be aware of
Content changes significantly affect user workflows
Adding substantial new information

DON'T create a new version when:

Fixing typos or minor errors
Adjusting formatting
Making editorial improvements
Updating links

Naming Consistency

Required Format:

Use lowercase v prefix: v1.0, v2.1
Always include minor version: v1.0 not v1
Match software version when applicable

Don't Use:

version-1.0, 1.0, V1.0, ver1.0

Version History Table

Requirement:

All documentation must include a version history table at the beginning of the document. This table tracks all versions and changes over time.

:::info Important List versions from newest to oldest (most recent version first). :::

import TableVersionHistory from '@site/src/components/TableVersionHistory';

<TableVersionHistory
  versions={['1.2', '1.1', '1.0']}
  dates={['January 2025', 'March 2024', 'January 2024']}
  descriptions={['Added new analysis features and updated documentation', 'Updated installation instructions and fixed bugs', 'Initial release']}
  modifiedBy={['John Doe', 'Jane Smith', '-']}
  reviewedBy={['Jane Smith', 'John Doe', 'John Doe']}
  approvedBy={['Project Lead', '-', 'Project Lead']}
/>

For detailed information about available props and advanced usage, see the TableVersionHistory component reference.

Troubleshooting Versions

New Version Not Appearing

Solutions:

Verify folder structure: docs/software-name/vX.Y/
Restart dev server: Stop (Ctrl+C) and npm start
Clear cache: npm run clear then npm start

Version Selector Not Working

Check:

Version metadata files exist in static/versions/
Folder names follow format: v1.0, v1.1, etc.
Each version folder contains at least one .mdx file

Fix:

# Stop the server (Ctrl+C) and restart
npm start

Wrong Default Version

Solution:

Default version is typically the highest version number
To change: Modify version detection script (advanced, contact site administrator)

Summary

Quick Reference:

Remember:

Each version is a complete copy in its own folder
All scripts run automatically during npm start or npm run build
Old versions remain accessible to users
Match software versions when documenting software releases

For more details on the build process and automation scripts, see Appendix B: Build Process Overview.

Navigation Menu

Uh oh!

Versioning System

Version Format: Major.Minor

When to Create a New Version

Major Version (X.0)

Minor Version (X.Y)

Updates Without New Version

Version Folder Structure

How to Create a New Version

Step 1: Determine Version Number

Step 2: Copy Existing Version Folder

Step 3: Update Content in New Version

Step 4: Copy Images/Assets to New Version Folder

Step 5: Copy and Update Bibliography

Step 6: Restart Development Server and Verify New Version

Step 7: Commit Changes and Open a Pull Request

Stage and commit

Push the branch to GitHub

Version Notice for Users

Best Practices

When to Version

Naming Consistency

Version History Table

Troubleshooting Versions

New Version Not Appearing

Version Selector Not Working

Wrong Default Version

Summary

Uh oh!

FilesExpand file tree

02-versioning-system.mdx

Latest commit

History

02-versioning-system.mdx

File metadata and controls

Versioning System

Version Format: Major.Minor

When to Create a New Version

Major Version (X.0)

Minor Version (X.Y)

Updates Without New Version

Version Folder Structure

How to Create a New Version

Step 1: Determine Version Number

Step 2: Copy Existing Version Folder

Step 3: Update Content in New Version

Step 4: Copy Images/Assets to New Version Folder

Step 5: Copy and Update Bibliography

Step 6: Restart Development Server and Verify New Version

Step 7: Commit Changes and Open a Pull Request

Stage and commit

Push the branch to GitHub

Version Notice for Users

Best Practices

When to Version

Naming Consistency

Version History Table

Troubleshooting Versions

New Version Not Appearing

Version Selector Not Working

Wrong Default Version

Summary