View on GitHub

tms-dms-cms-usage-guide

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

Falcon BMS TMS/DMS/CMS Guide Version System v4.2.1

Latest Update: 02 February 2026, 23:00 -03
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.

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.

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.

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

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.

6.3 Archival Strategy

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

6.5.2 Releases

6.5.3 Milestones

6.5.4 Workflow Integration

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

7. Consolidated Quick Reference

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 v4.2.1

Document Status: Production-Ready (v4.2.1)
Effective Date: 10 January 2026
Last Updated: 02 February 2026, 23:00 -03