Version Control

Published:  2017-03-31

Category:  General

Nickname:  "Buzzkill Version Control"

Lead Engineer:  Jimmy Holub

Contributing Engineers:  *

System Configuration Files

• {Prefix} _ {Major} . {Minor} . {Patch}

  • This standard is based upon "Semantic Versioning":  https://semver.org  Please check out that website before reading any further.

    • Key concept:  to indicate the "degrees of compatibility".

    • Major increment:  Not compatible with previous version.

    • Minor increment:  New functionality, compatible with previous version.

    • Patch increment:  Bug fixes.

  • Base Prefix = 1 to 4 characters.

    • Example:  "CW" (CrossWalk Church)

    • Some system configuration files may have additional identifiers within the prefix.

  • The prefix is followed by an underscore ( _ ).

  • If you anticipate more than 9 iterations of an element, then use leading zeroes so that the filenames sort properly in file explorers.

  • Examples:

    • CW_2.1.1

    • CW_10.02.01

    • CW_09.04.03  (Hey, Cowboy!  Please use a leading zero, because otherwise "10" precedes "9" when sorted.)

• Occasionally, a single "Documentation" file may apply to several Minor or Patch versions of a System Configuration File.  In that case, it may be appropriate to insert the letter "x" as a variable, instead of a number.  Also, you will notice that, if a Minor element is replaced with a variable, then it would be "redundant and unnecessary" (ha ha) to use a variable for the Patch element.  Examples:

  • CW_3.x

    • (Note the omission of the Patch element because the Minor element is a variable.)

  • CW_3.4.x

General Documents

• Simplified Format:  {Document Title} {Space} {Major} . {Minor} . {Patch}

  • The full title serves as the Prefix.  (Okay to use abbreviations for file names.)

  • Simply add a proper Semantic Versioning number to the end of the title.

  • Examples:

    • Sermon Audio Podcast Instructions 2.0.3

    • Version Control Conventions 1.1.0

• Enhanced Format:  {Document Title} {Comma} {Space} {"v"} {Major} . {Minor} . {Patch}

  • If the Prefix (i.e. title) has any numbers at the end (such as date), then insert a comma + blank space + "v" to provide intuitive separation between the numbers at the end of the title and the version number.

  • It is okay, but not necessary, to always use this format.

  • Examples:

    • Easter Sunday Schedule 2017-03-31, v1.2.3

    • How to Use the Church Phone System, v9.1.1

• Truncation

  • You may also omit the use of the "Patch" element if it seems superfluous for that document.

  • Examples:

    • Brainstorm Draft of Air 0.0

    • How to Write Ridiculous Standards and Not Have Readers Fall Asleep, v142.00.86