[TL;DR]:
- romType will increase with every released ROM
- Check romType if your program uses features that are not present in ROM v1
- Only features described in interface.json should remain stable over ROM versions
Purpose of romType variable
The intent is that GT1 applications can detect the presence of ROM features by inspecting only this memory location. There are two types of ROM features: those listed in interface.json, and those not listed there. Features might still be described elsewhere, but just by being documented doesn't make a feature part of the intended, stable, interface. The goal of interface.json is to provide a STABLE interface between GT1 files and ROM versions that can load such files. We only add new things to interface.json, never(*) remove, rename or change bindings once they are defined. This should help with future compatibility of GT1 files. Things that are not in interface.json can, and will, disappear or change at any time and should not be relied upon. (For example: some zero-page variables used by the video loop, certain SYS functions, specific entry points in code pages, location of application ROM images, built-in pictures, the shape of the font, values in ROM addresses etc...).
Value increases with ROM releases
romType is an unsigned 8-bit value that strictly goes up with each "official" ROM release, no matter how small the delta. So if you want to test for the presence of a feature, compare the magnitude of this value to that of the first ROM that introduced it. For historic reasons, the first romType value was 0x1c for ROMv1. Don't rely on the meaning of individual bits. Also, the value can go up by an arbitrary number with each release, so there no way to "calculate" the displayed version name as will be known by the user.
With this it is not possible that two "official" ROM releases have the same romType value. However, third-party ROMs with compatible GT1 loading capability are adviced to use the same romType value as the ROM version they were derived from.
End user is in control
The romType value is in RAM, not ROM! This is on purpose, so that the end user always has an escape hatch and can put a value in there that a troublesome GT1 file expects to see. The user has the final say on what happens on the system, not the file... So please don't try to second-guess the romType value as a programmer.
Don't crash
GT1 files that need a certain interface feature that is not present in earlier ROMs should degrade in performance or functionality, or fail gracefully, but definitely NOT crash. By publishng a file as GT1 you're signaling that you expect the file can be loaded with any past, present or future ROM version. To help remind the programmer which features were introduced after ROM v1, and therefore require a romType check before use, we'll add a ROM version number to their names.
32K vs. 64K
It is understood that a program that really requires an extended 64K memory crashes while loading on a 32K system. In that case please end the filename with "_64K.gt1". The main idea is still that a user doesn't get unexpected surprises.
Hack files
Of course the Gigatron is an open system, so there will be plenty of methods to detect what kind of ROM you're running on. If you make a GT1 file that you know depends on undocumented features (or better phrased: features not listed in interface.json), it is adviced to give it a different extension. For example 'Demo3_ROMv1only.gt1x' (I always append a 'x' to such experimental files with no expectation of compatibility.)
Evolution and process
We should be pragmatic about these rules. A list of simple numbers won't ever fully describe the exact boundary of the INTENDED interface: there will always be some assumptions that remain implicit, such as the meaning of certain values or the exact sequence of certain events. It is also possible that some feature wasn't declared as a stable interface, but that there are good reasons to make it so retro-actively. Please feel free to discuss in GitHub or in the user forum. Basically you're then asking "I'm using this implicit feature now and I would like it to keep working in future ROMs, can we fixate it and document it?".
Incompatible ROM upgrades
If we ever decide to make a truly incompatible step in ROM versions, one that breaks many GT1 files out there, we should start using a different extension for object files for what then has effectively become a new platform (GT2 comes to mind). This is conceivable if we ever change something really big about the architecture, such as the memory map or the vCPU instruction set. Of course we hope we can get very far without ever doing something like this...
(*) Have said that, we retro-actively removed 'SYS_Reset_36', 'SYS_NextByteIn_32' and 'SYS_LoaderPayloadCopy_34' from the interface files. Their inclusion turned out to be a bit premature and they had to change after ROM v1. There will be no alternative for SYS_ReadNextInput_32 and SYS_LoaderPayloadCopy_34 in interface.json soon: it is part of Loader, but that is logically not a GT1 file. 'SYS_Reset_36' was just an intermediate in the soft reset sequence. The proper way to initiate that is by redirecting the vCPU to vReset (0x1f0). So we have retro-actively added vReset to the interface.json files instead.