The usefulness of this library to the content delivery team can best be illustrated through the example of the “content migration” sub-team. This team acts as a bridge between the editorial function and the fabrication pipelines (which subsequently deliver content for delivery to users of the main product web page). The content is mastered in XML using a variety of DTDs but the definitions in these DTDs are quite broad, in the sense that several different types of content can be represented using the same DTD. However, for delivery to the production systems certain additional rules must be enforced—these rules (written in Schematron) “tailor” the broad DTD definition for each particular content type.
The Schematron rules effectively represent the editorial requirements for the content—there are many of them and they change quite often. The content migration sub-team develops and maintains these Schematron rules, supplying them to the fabrication team for inclusion in the various pipelines related to those content types. Prior to the development of the Ant library the typical workflow was something like:
Find the appropriate build.xml file and edit it, commenting out details of other team members content types and un-commenting their own.
Find another, apparently unrelated build.xml file (e.g. with a relative path similar to “../../common/build.xml”) and make similar changes.
Run the first build file to create a pre-compiled Schematron file (i.e. an XSLT).
Manually move the output file to a different folder.
Inform the fabrication team that there is a new version of the file.
Liaise with fabrication to correct any issues found during the next run of the content through its pipeline. This may include confirming which version of the code is being included and re-compiling if necessary.
Note that as all code was shared in the same TFS repository it was very difficult to go back and check the status of any particular version. Different versions were not explicitly labelled and any changes to the code might be overwritten by another team member committing to the same files in the same repository.
Therefore, after the Ant library was developed a second, higher level set of macros was developed to assist the content migration sub-team. The Schematron files for each content stream were placed in their own Git repository and which had its own (Ant) properties file that described how the Schematron files should be compiled and the various options that should be applied. A standard template for a build.xml file common to all the content streams was also created. The workflow now became:
Create a new feature branch in the repository and make the code changes required.
From a command line run $ ant compile to
compile the Schematron files (using the
compile-schematron macros).
Run $ ant validate to validate the compiled
Schematron against a representative data model, or series of
models (using the validate-schematron
macros).
Merge the feature changes back into master (and repeat from step 1 for additional features).
Once all features have been finished create a “release” branch,
Run the validation tasks once more. If all the tests are valid
then run $ ant version to update the
version number—this version number is now embedded in the
compiled Schematron.
Prepare release documentation and run
$ ant docs to prepare it. This
documentation will be deployed with the compiled Schematron
files so that all content developers can see what changes have
been made and why. The build file will check that this
documentation has been completed and will not deploy until it
has.
Run $ ant deploy to deploy the compiled
Schematron files to the CAPE for reference as well as
deploying them directly to a network share where the
fabrication pipeline will pick it up automatically. This uses
the deploy-files macros, but the standard
build file will not allow deployment from other than a release
branch or if there are outstanding commits. In other words,
the developer cannot deploy simply “as a
test”—they must think about their actions.
Merge the feature branch back into master and push to the server to keep a record of all changes.
This freed up the content migration sub-team to concentrate on the details of the content and the Schematron rules, dealing with actual content issues rather having to continually having to manually configure build files at each step. Furthermore, the addition of a version number meant that any errors encountered in the fabrication pipeline were much easier to track and resolve. Of course, some of these improvements are directly related to the enforcement of the Development Policy—but most of the time this is accomplished automatically through the Ant library macros.