View on GitHub

tms-dms-cms-usage-guide

Structured online and PDF guide for Falcon BMS and other F-16 flight simulators covering TMS, DMS and CMS HOTAS switch functionality and usage

Falcon BMS TMS/DMS/CMS Guide Version System

Latest Update: 01 March 2026 Effective Date: 10 January 2026

Repository Identification

0. How to Use This Document

0.1 Initial Question

Before any version change, answer:

0.2 Decision Steps

  1. Identify the type of change made in the work session:
    • Did a new chapter enter the main guide content?
    • Was there a strong restructuring of sections or of how tables organize content?
    • Were there only small adjustments to text, formatting, or table cells?
  2. Go to the appropriate “When to Increment” table:
    • If still in 0.x.x.x → use Quick Reference (0.x.x.x — pre-publication).
    • If already in ≥ 1.0 → use Quick Reference (x.x.x — post-publication).
  3. Apply the File Naming and Snapshot Workflow:
    • Update the version and date macros in the guide’s LaTeX preamble.
    • Save an updated snapshot file under wip/guide/ with the new number and date.
    • Copy this snapshot over guide.tex in the repository root so both files are identical.
    • Update PROJECT-TRACKING with the new entry.
    • Move the previous snapshot to archive/GUIDE/.
    • Create a GitHub tag and release for the new version.
    • If pre-release infrastructure is active: also consult the Alpha Snapshot Workflow in §6.2 before creating a new official snapshot. Alpha snapshots follow a separate naming pattern (§2.1) and workflow (§6.2).

0.3 Scenario-Based Examples

1. Header and Scope

1.1 Metadata

1.2 Purpose

1.3 Scope

1.4 Version Fields in the Guide’s LaTeX

The guide contains version and date macros in the preamble, for example:

\newcommand{\docversion}{0.3.3.0}     % Document version number
\newcommand{\docbuild}{20260202}      % Build date YYYYMMDD
\newcommand{\docstartdate}{05 January 2026}
\newcommand{\docenddate}{DD MMM 2026}
\newcommand{\chapterscompletedof}{3/7}
\newcommand{\tablesfilledpct}{0\%}
\newcommand{\fulldocversion}{\docversion+\docbuild}

These macros are the internal source of truth for the document version.

On every version change:

The version number stored in these macros must always match:

1.5 Repository Structure and GitHub Workflow

To align the version system with GitHub branch protection and readable diffs, the repository follows these rules:

2. Global Naming Convention

2.1 Snapshot File Name Rule

Every snapshot of the main guide stored in wip/guide/ must follow this pattern:

guide-vMAJOR.MINOR[.PATCH[.SUBPATCH]]-YYYYMMDD.tex

The root file guide.tex keeps a stable name and is always a byte-identical copy of the latest snapshot that represents the active version.

Alpha pre-release snapshots follow a separate pattern and reside in wip/ root:

wip/guide-vMAJOR.MINOR.PATCH.SUBPATCH-alpha.N[.M]-YYYYMMDD.tex

2.2 Date Format

2.3 Examples

3. Pre-Publication Regime (0.x.x.x)

3.1 Semantics of Digits in 0.x.x.x

During pre-publication, the version number has four digits:

0.MINOR.PATCH.SUBPATCH

3.2 Increment Rules in 0.x.x.x

Only MAJOR is fixed (0); the other digits vary according to change type.

3.2.1 Central Rule

3.2.2 “When to Increment (Pre-Publication)” Table

Situation Increment Note
Integrate a new chapter with substantive content MINOR Example: 0.2.x.x → 0.3.0.0.
Add a new relevant section in an already active chapter PATCH Example: 0.3.1.0 → 0.3.2.0.
Restructure chapter sections/subsections PATCH Keeps MINOR; changes internal architecture.
Fill/modify tables in a way that changes how the chapter is used PATCH Example: new HOTAS table that reorganises reading.
Fix LaTeX syntax errors that prevented compilation PATCH Structural “major bugfix”.
Fix typos, punctuation, small wording adjustments SUBPATCH Example: 0.3.2.0 → 0.3.2.1.
Adjust few table cells without changing logic/structure SUBPATCH Local refinement.
Only compile/save, with no content change Date Update YYYYMMDD, not version number.
Work in non-integrated WIP (chapter-...tex, section-...tex, etc.) None Version only goes up when content enters the snapshot and guide.tex.
Create alpha snapshot (pre-release infrastructure active) None Alpha versioning is separate from the official version line (see §6.5.1).

3.2.3 Internal Phases as Metadata

3.3 Role of Tables in 0.x.x.x

3.3.1 Tables as Part of Chapters

3.3.2 Tables and Version Increments

3.4 Practical Examples (0.x.x.x)

3.4.1 Actual Pre-Publication Evolution

The following reflects the actual progression of the guide:

Version Date Content Integrated
v0.1.0.0 2026-01-05 C1 Introduction — initial structure
v0.2.0.1 2026-01-07 C5 CMS Section 5.1 integrated (2nd chapter with content)
v0.2.4.0 2026-01-12 C5 CMS complete (§5.1, §5.2, §5.3)
v0.3.0.0 2026-01-15 C4 DMS Sections 4.1 and 4.2 integrated (3rd chapter with content)
v0.3.1.0 2026-01-18 Preamble infrastructure upgrade (article → report class)
v0.3.2.0 2026-01-19 C4 DMS Section 4.3 integrated
v0.3.2.1 2026-01-29 Hotastable environment upgrade, C4/C5 corrections
v0.3.3.0 2026-02-02 C4 DMS complete (§4.4), C1 Introduction revised
v0.4.0.0 2026-02-10 C2 HOTAS Fundamentals + C3 DMS integrated; chapter renumbering (DMS: C4→C3, TMS: C3→C4)
v0.4.1.0 2026-02-11 Infrastructure upgrades: hotastable v2.1, cross-reference macros, List of HOTAS Tables
v0.4.1.1 2026-02-18 Minor wording corrections; missing \label tags added to C5 hotastable environments

Projected future:

3.4.2 Mini-Cases by Scenario

4. Bridge to Publication (0.x.x.x → 1.0)

4.1 Criteria to Declare 1.0

A 0.a.b.c version can be promoted to 1.0.0 when all criteria below are met:

4.2 Transition Procedure

  1. Choose base 0.a.b.c.
    • Select, among existing 0.x.x.x versions, the one that best represents the state “ready for 1.0”.
    • Confirm it meets the criteria in Section 4.1.
  2. Create version 1.0.0.
    • Update macros in the guide LaTeX snapshot: 
      \newcommand{\docversion}{1.0.0}
\newcommand{\docbuild}{YYYYMMDD}  % Date when 1st edition is frozen
    • Save the snapshot with the new name under wip/guide/: 
      wip/guide/guide-v1.0.0-YYYYMMDD.tex
    • Copy this snapshot over guide.tex in the repository root so both files are identical.
  3. Freeze the 0.x.x.x line.
    • Ensure all guide-v0.*.tex files are in archive/GUIDE/.
    • Do not create new 0.* versions after 1.0.0 is born.
    • The 0.x.x.x line becomes pre-publication history only.
  4. Update tracking and GitHub.
    • In PROJECT-TRACKING, record:
      • Which 0.a.b.c version was promoted to 1.0.0.
      • A short editorial justification for promotion (why this is the 1st edition).
    • Create GitHub tag v1.0.0 and corresponding release with changelog.

4.3 Cutover between Regimes

4.4 Checklist before Promoting to 1.0.0

Before performing the transition, validate:

5. Post-Publication Regime (≥ 1.0, x.x.x Scheme)

From 1.0.0 onwards, the focus moves from internal development to edition and revision management for readers.

5.1 Semantics of Digits in x.x.x

After the first published edition, the guide uses:

MAJOR.MINOR.PATCH

5.2 General Increment Rules in x.x.x

5.2.1 General Principles

  1. Editorial compatibility.
    • If the reader can use the new version as a drop-in replacement for the previous one, without relearning global structure → generally not MAJOR.
    • If the new version requires rethinking stable references (chapter number, global order) → candidate for MAJOR.
  2. Frequency.
    • MAJOR is rare (editions).
    • MINOR is less rare, but still signals important revisions.
    • PATCH can happen more frequently (errata, polish).
  3. Continuity with 0.x.x.x.
    • 0.x.x.x becomes pre-publication history; in ≥ 1.0, avoid unnecessary architecture resets.

5.2.2 “When to Increment (Post-Publication)” Table

Situation Inc. Comment
Reorganise chapter structure (merges, splits, large order changes) MAJOR Reader sees it as a new edition of the guide.
Add/remove large content blocks that change global scope MAJOR For example, whole new part, or removal of a dominant part.
Adapt guide to a new major BMS version with substantial rewrite of several chapters MAJOR Old content is no longer fully current.
Add a new important chapter within the same edition MINOR Scope expands, edition remains the same.
Substantially expand one or more chapters (new sections, key tables) MINOR Significant improvement without breaking global organisation.
Reorganise internally a subset of chapters, keeping index recognisable MINOR Revised edition within same MAJOR.
Correct several localised content errors in text/tables PATCH Focus on fixing, not expanding scope.
Fix typos, grammar, improve clarity, update references PATCH Typical errata/polish versions.
Adjust few table cells, change labels without altering logic PATCH No chapter renumbering or flow changes.

5.3 Role of Tables in ≥ 1.0

5.4 Example Progression in x.x.x

5.4.1 From the 1st Edition Onward

5.4.2 Decision Examples

5.5 Interaction with 0.x.x.x History

5.6 Quick Checklist for ≥ 1.0

  1. Does your change alter the edition (reader should perceive it as a new edition)?
    • Yes → MAJOR (for example 1.3.2 → 2.0.0).
    • No → continue.
  2. Does your change significantly expand scope or reorganise an important part, while staying in same edition?
    • Yes → MINOR (for example 1.0.0 → 1.1.0).
    • No → continue.
  3. Is your change local (fixes, clarifications, small table/text adjustments)?
    • Yes → PATCH (for example 1.1.0 → 1.1.1).

6. Rules Common to Both Regimes

6.1 Build Date and Compilation

6.2 File Naming and Snapshot Workflow

Single workflow for 0.x.x.x and x.x.x:

  1. Determine change type.
    • Use the appropriate “When to Increment” tables (pre- or post-publication).
  2. Update version/date macros in LaTeX.
    • Set \docversion to the new number.
    • Set \docbuild to the new YYYYMMDD date.
    • Ensure \fulldocversion reflects the correct combination.
  3. Compile and check for errors.
    • Generate the PDF and check LaTeX warnings/errors.
  4. Save the snapshot under wip/guide/.
    • Apply the pattern: 
      wip/guide/guide-vMAJOR.MINOR[.PATCH[.SUBPATCH]]-YYYYMMDD.tex
  5. Propagate to the canonical file.
    • Copy the new snapshot over guide.tex in the repository root so that Git/GitHub see the change as an update of the same file.
  6. Archive previous snapshot.
    • Move the previous guide-v*.tex from wip/guide/ to archive/GUIDE/.
  7. Update PROJECT-TRACKING.
    • Add a line with version, date, affected chapter(s), and a concise description of the change.
  8. Create GitHub tag and release.
    • See Section 6.5 for details.

→ Visual reference: WIP Integration Flow

Alpha Snapshot Workflow (parallel, optional):

For pre-release alpha snapshots (activated only when pre-release infrastructure is in progress):

Phase 1 — Creating the alpha pre-release:

  1. Determine content. Identify which chapters have reached alpha WIP status. A WIP file transitions to alpha when the author decides to include it in a pre-release snapshot (see WIP-FILE-NAMING §3.3.1 for the final → alpha transition rules).
  2. Create alpha snapshot. Starting from either the current wip/guide/guide-v*.tex snapshot or the template (template/template-wip.tex), integrate all alpha-approved chapters (cumulative — alpha.N includes all previously alpha-approved content). Save as: wip/guide-vMAJOR.MINOR.PATCH.SUBPATCH-alpha.N[.M]-YYYYMMDD.tex
  3. Compile and check. Generate PDF from the alpha snapshot. Verify no errors.
  4. Create Git tag. Tag format: vMAJOR.MINOR.PATCH.SUBPATCH-alpha.N[.M]
  5. Create GitHub pre-release. Mark explicitly as pre-release. Attach compiled PDF.

Note: The official snapshot in wip/guide/ is NOT updated during Phase 1. Alpha snapshots remain in wip/ root until promoted to official.

Phase 2 — Promoting alpha to official:

  1. Rename to official snapshot. Drop -alpha.N[.M] from the final alpha snapshot name and save to wip/guide/guide-vMAJOR.MINOR.PATCH.SUBPATCH-YYYYMMDD.tex.
  2. Resume standard workflow. Follow steps 3–8 above (compile, propagate to guide.tex, archive previous snapshot, update PROJECT-TRACKING, create official tag and release).
  3. Archive alpha snapshots and WIP files. Move all guide-v*-alpha.*.tex from wip/ root to archive/GUIDE/. Rename all associated WIP files from alpha → approved status and move them to archive/WIP/ in batch (see WIP-FILE-NAMING §4.3).

→ Visual reference: Alpha Supplement

6.3 Archival Strategy

Alpha snapshots: Only the current (most recent) alpha snapshot remains in wip/ root. When a new alpha is published (N increments), the previous snapshot is superseded and may be moved to archive/GUIDE/ immediately. The current alpha snapshot stays in wip/ until the official release is created, at which point it is also moved to archive/GUIDE/. Alpha WIP files (chapter-*-alpha-*.tex) are unaffected by this rule — they remain in wip/ until the official release.

6.4 Relationship with WIP File Naming and BRIEFING

6.5 GitHub Integration: Tags, Releases, and Milestones

The version system integrates with GitHub’s release management features:

6.5.1 Tags

Alpha (pre-release) tags:

Alpha version increment rules (parallel to the canonical version-system):

Change in snapshot Canonical equivalent Alpha counter
New chapter added to snapshot MINOR N++ — M disappears (alpha.2)
Any correction below chapter level (structural or minor) PATCH or SUBPATCH M++ (alpha.1.1, alpha.1.2)

Notes:

6.5.2 Releases

Pre-releases (alpha):

6.5.3 Milestones

6.5.4 Workflow Integration

Issues (in Milestone) → WIP files → Integration → Snapshot → guide.tex → Tag → Release
                                                                                    ↓
                                                                          Close Milestone

ALPHA PATH (parallel, optional):
WIP files (final) → [author decides alpha] → alpha status → Alpha Snapshot (wip/) → Alpha Tag → Pre-Release
                                                                                                    ↓
                                                                              (awaits official integration)
                                                                                         ↓
                                                                          Official flow resumes from Integration

Note: Promotion from alpha to official (Phase 2) requires an explicit author decision — it does not happen automatically.

7. Consolidated Quick Reference

→ Visual reference: Version System Diagram

7.1 Quick Reference (0.x.x.x — Pre-Publication)

Key Situation Pre Version (ex.) Post Version (ex.)
New chapter with content enters guide 0.2.4.0 → 0.3.0.0 —
New section in existing chapter 0.3.1.0 → 0.3.2.0 —
Important table changes chapter usage 0.3.2.0 → 0.3.3.0 —
Typos and micro wording fixes 0.3.2.0 → 0.3.2.1 —

7.2 Quick Reference (x.x.x — Post-Publication)

Key Situation Pre Version (ex.) Post Version (ex.)
Second revised edition (broad change) — 1.3.2 → 2.0.0
Important new chapter within same edition — 1.0.0 → 1.1.0
Minor fixes and clarifications on 1.1.0 — 1.1.0 → 1.1.1

7.3 Key Notes

End of document — Version System

Document Status: Production-Ready Effective Date: 10 January 2026 Last Updated: 24 March 2026