XPlane2Blender Version Spec

XPlane2Blender Version Spec

In short: Modern: ({ } is used for visual separation only, not part of the spec

{major}.{minor}.{revision}-{build type}.{build type version}+{data model version}.{build number}

Anything that doesn't match this will be called a legacy build, and any components that didn't exist in the legacy version will have 0's (or equivalent) for their values.

Due to the limitations of Github's allowed names for zip files, the naming scheme is slightly altered for file uploads. (This has been accidentally changed several times, so, consider 3.5.0-beta.2 to be a fresh start of this system)

{major}_{minor}_{revision}-{build type}_{build type version}-{data model version}_{build number}

Components

Blender Addon Version

• A tuple of ints, (major,minor,revision)

Used to tell Blender the version of the addon, communicate to users the major differences in versions of the program.

• Major - Only increments with major versions of Blender or the program itself
• Minor - Only increments with when introducing large backwards compatibility issues
• Revision - Smaller features and bug fixes

Build Type

• A string of from the legal build_types (see table below)

Type (in order of precedence)	Description
"legacy"	Legacy build numbers, blender addon version will be only valid information.
"dev"	Unstable pre-alpha development build
"alpha"	For alpha cycle
"beta"	For beta cycle
"rc"	Stands for "release candidate", used for when we count a version of the software as a full public release

Another indicator of how safe it is to use this version on production scenes. Legacy build refers to anything less than 3.4.0-beta.5 - specifically "2.49.2", "3.2", "3.20.0"-"3.20.14", "3.3.0" - "3.3.13", or "3.4.0".

The 2.49 scripts actually had several version numbers, but for our purposes we just want to communicate this file was once converted.

Build Type Version

• An int representing which iteration in the development cycle of the chosen build type
• "alpha", "beta", and "rc"'s build type version always increment with every new release and is always >= 1. "legacy" and "dev" always have a build type of number of 0.

Data Model Version

• An int representing the version of data model XPlane2Blender; the collection constants, properties, and how the updater handles forwards and backwards compatibility
• Must be incremented with every change of anything that affects the XPlane2Blender data model, almost entirely found in xplane_constants, xplane_props, and xplane_updater. Always 0 for legacy builds, a number > 1 for every other build type
• When merging, always take the greater of the differences, and increment again

Build Number

• A string representing the build number, the YYYYMMDDHHMMSS from the Unix epoch in UTC. No build number is stored as "NO_BUILD_NUMBR" and is shown as such.
• Build numbers are created (preferably) every time the build script is run or (worst case) by hand with extreme care.

Location of Definitions

Component	Data Definition	Git Tracked?	On Merge
Blender Version	bl_info["version"] in __init__.py	Yes	Take what makes sense
Build Type	BUILD_TYPE in ``xplane_config.py	Build type should be kept from its parent branch during a testing cycle	Take what makes sense
Build Type Version	BUILD_TYPE_VERSION in ``xplane_config.py	Yes, always	Take what makes sense
Data Model Version	DATA_MODEL_VERSION in xplane_config.py	Yes, always	If changing key files, take whichever is higher and increment by 1
Build Number	BUILD_NUMBER in xplane_config.py	No, only the build script will replace the value of that constant	N/A

Human readable formats

The version will be exposed to the user in the following ways

• In the addons menu, when in a non-release candidate build a warning will be displayed using bl_info["warning"]
• In the scene settings, before the XPlaneLayers section or (in root mode) Advanced Settings, with degrees of warning as needed
• In the footer of every OBJ file

As per semantic versioning, here is a rough regex (without escapes or capturing groups) to capture what our version number looks like Modern: major.minor.revision-build_type.build_type_version+data_model_version.build_number

Legacy: major.minor.revision

Binary Data

In .blend files, the current version will be saved in bpy.props.scene.xplane.xplane2blender_version as a PropertyGroup. In addition, a history of every version that the .blend file ever encountered will be stored in bpy.props.scene.xplane.xplane2blender_version_history as a CollectionProperty. We will never accept an invalid version into the history.

bpy.props.scene['xplane2blender_version'] will be deprecated, it's contents will be copied to the new format, however much possible, and deleted to avoid confusion.

Build Script

The build script will need to replace the following source code locations Location | Content bl_info's "warning" member|Warning messages when not in a release candidate

Other project version numbers

Future tag numbers will only include the addon version, build_type, and build_type_version prepended with a v. Topic branches will continue to start with their bug number (always!) Testing cycles branches are in the form of v3-4 (doesn't start with a number, like topic branches do).