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:

1. Is this a new document?

   • Use v1.0 for the first version of a new document

2. Are you adding/removing chapters?

   • Yes → Major version (e.g., v1.0 → v2.0)
   • No → Continue to next question

3. 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:

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

Step 3: Update Content in New Version

1. Make your changes in the new version folder only
2. Leave the old version folder unchanged
3. 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.

1. Create new version-specific folder:

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

2. 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

3. Add any new images to the new version folder

4. Remove any images no longer used in the new version

5. 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:

1. Create new version-specific folder:

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

2. 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

3. 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

4. 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:

1. Check Version Selector:

   • Look for dropdown in top navigation
   • Verify new version appears in list
   • Click to switch between versions

2. 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

Using GitHub Desktop

✅ Stage and Commit Changes

1. Open GitHub Desktop
2. You should see all changed files listed in the left sidebar under "Changes"
3. Review the changes in the diff viewer on the right
4. Enter a commit message in the Summary field (e.g., "Add v1.1 documentation with updated usage guide")
5. Optionally add a more detailed Description
6. Click Commit to main (or your current branch)

✅ Push Changes to Remote

1. After committing, click Push origin in the top toolbar
2. Your changes will be uploaded to the GitHub repository

Using Git (Command Line)

✅ Stage, Commit, and Push Changes

# Stage all changes
git add .

# Commit with descriptive message

git commit -m "Add v1.1 documentation with updated usage guide"

# Push to remote

git push origin main

---

Version Selector for Users

The version selector appears in the top navigation bar, allowing users to switch between documentation versions.

How It Works:

• Automatically populated from version folders
• Shows all available versions for that documentation
• Preserves current page when switching (if page exists in both versions)
• Redirects to homepage if page doesn't exist in selected version

Default Version:

• Latest version is set as default for new visitors
• Last selected version remembered in browser

---

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.

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:

1. Verify folder structure: docs/software-name/vX.Y/
2. Restart dev server: Stop (Ctrl+C) and npm start
3. Clear cache: rm -rf .docusaurus 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:

Action	Version Change
Fix typo	None
Expand section with examples	Minor (X.Y)
Add new chapter	Major (X.0)
Rewrite multiple chapters	Major (X.0)
Update for software patch release	Minor (X.Y)
Update for software major release	Major (X.0)

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.