Data File Release (Savage)
The data files that we've been developing are finally complete and soon ready to be shared with others. The sections below address a variety of final tasks associated with preparing our data files for distribution.
Every new release of HL typically introduces new functionality within the Kit. If you utilize this functionality in your data files, you'll want to be sure that users don't try to load your files with an older version of HL. If they do, they will get errors when compiling the data files and think that the files are the problem. You can avoid this by designating the minimum version of HL that is required with your data files.
Within the definition file, the "release" element possesses a "required" attribute. This attribute can specify the minimum version of HL that your data files require. If you specify this correctly, any attempt by the user to load your data files into an older copy of HL will result in an appropriate error being reported. The user will be we told he needs a newer version of HL and pointed to the Updates mechanism to retrieve the update.
Since our data files are utilizing functionality introduced in V3.1 of HL, we need to specify that as our requirement. So the attribute is must be assigned the value "3.1".
When we release new updates to our data files, we're going to want to differentiate the newer version from any older versions. To accomplish this, each new release of our data files must be assigned a distinct version number.
The data file version number is used by HL to determine whether a new version is available. It is also used to detect when a loaded portfolio requires a newer version of the data files. This can happen if the portfolio is created on one computer and then loaded on a different one with a different version of the data files.
Just like HL itself, the version number used by data files has two pieces. There are both a major and minor version. In general, increasing the major version indicates that major changes and/or enhancements have been made to the data files. If the revision are relatively small in a new release, then the minor version number should typically be increased instead. When you increase the major version number, you should normally reset the minor version number to zero. Every time you release a new update to your data files, you should always increase the version number.
If you are releasing preliminary data files to friends for testing before you release the files widely, then you should probably assign a major version of zero and increment the minor version with each such release. When you officially release your data files for the very first time, you should normally assign a version of "1.0" (i.e. a major version of one and a minor version of zero). Since we're now ready to release our data files for the first time, that's the version we'll assign to our data files.
Within the definition file, you can specify a block of text referred to as "release notes". This block of text is shown to the user when they load your data files for the first time. Within the release notes, you should provide basic information to the user regarding your data files, including where to find further information (like the User Manual), legal text, and the like.
You can specify whatever information you like within the release notes. However, we recommend that you use a similar approach to how the data files for other game systems are handled. This ensures that users have a consistent experience across all game systems, which makes everything easier to use.
You should ideally maintain a FAQ for your data files. The acronym "FAQ" is short for "Frequently Asked Questions". You can define your FAQ with two different methods, and either one is perfectly acceptable. The first option is to include the FAQ as a section within the User Manual for your data files (see below). The second option is to use the built-in FAQ mechanism provided by the Kit. This latter approach allows you to define the individual FAQ entries as part of the data files and then allow the Kit to synthesize the appropriate FAQ document as an HTML file.
As implied by its name, the FAQ contains an assortment of answers to questions that users will be asking about your data files. When you first develop your data files, the list will likely be short, but you will usually be able to anticipate at least a few questions that users will ask. If you provide answers before users ask them, it will make using your data files much easier for users and eliminate the annoyance of having to answer the questions when users bug you with them.