RD3: Versioning the Easy Way
Did you know that there is an FAA requirement that Audiovisual Programs, Computer Software Programs, Training Manuals, Workbooks, Handouts, and Other Courseware are subject to a revision process, which includes revision numbers?
The reference for this requirement can be found at 8900.1 Vol. 3 Ch 54 Sec 6, Part 142 Training Centers: Evaluate Training Programs, Curricula, Flight Training Equipment, and Recordkeeping Requirements (faa.gov), section 3-4437.
Why Are Revision Numbers Needed?
The purpose of this revision number is to indicate to the customer that something has changed in a module. That change needs to be reviewed by the customer, and possibly by the organization’s CAA inspector.
Typically, a revision number would be something along the lines of A.B.C where A, B, and C are integers that represent something. Usually, “A” would be used for a major revision, “B” for a minor revision, and “C” would be used for a build or publish version.
The problem with this type of system is that the determination of what constitutes a major or minor revision can be highly subjective. In addition, if the numbers are not incremented automatically, you run the risk of changing the numbers incorrectly. In a worst-case scenario, you may forget to update them in the first place.
RD3 Eliminates the Subjectivity of Revision Numbers
Our system is not subjective at all. We make no effort to distinguish a major revision from a minor one. Instead, we use something that is generated automatically and reliably – the time stamp.
For example, if the time stamp is 2017-12-04 17:30:00, our revision number would be 17.1204.1730. This basically equates to the:
- Last two digits of the year
- Two-digit month + two-digit day
- Two-digit hour + two-digit minute
The reason we use the hours and minutes as well is to cover the cases where multiple updates or publishes are made in the same day.
According to the requirement, this revision number must appear on every screen (called a scene in the RD3 system), and we obtain this value from the database when the module is first launched.
Each course project in RD3 has literally thousands of time stamps. Each row in the database has a timestamp that is automatically updated whenever we insert or update a record. The audio and video files have two time stamps:
- The original creation date
- The modified date
When a file is modified, we upload it to the server using RD3, and the system gets the modified date and converts it to UTC time. It copies the file to the proper location and then updates a database table that we call the Master Manifest. That table contains a list of all the files used by the course and includes their latest time stamp.
Controlling the Versioning Process Is Easy with RD3
The purpose of this timestamp is for versioning, but it’s primarily used to control the publishing process. RD3 relies on two servers. One is called the development server. This is the server where all the work is done. The second server is called the production server, and it’s responsible for distributing the course to the users either through your LMS, our LMS, or the Portable Classroom (offline viewer).
These timestamps are not all the same because they’re updated based on the server time whenever an upload occurs or a data point is changed, and you can literally have thousands of time stamps that are different from each other. We obviously don’t want to change the revision number simply because we corrected a typo on a graphic or changed the punctuation in a narration, so we had to devise a method that only updates the revision number when warranted.
When we initially publish a course, we set a flag in the database to indicate that project has already been published, so any changes made to the course afterwards are stored in a log. This log contains a description of what was changed. When the project is updated on the production server, a list of all the changes that have been published is displayed and the person making the update selects which revisions materially alter the course. The revision number is then updated using the highest timestamp of all the selected changes.