diff --git a/TCW/tcw31.xml b/TCW/tcw31.xml index 6011c04..944b667 100644 --- a/TCW/tcw31.xml +++ b/TCW/tcw31.xml @@ -25,8 +25,11 @@ - Update procedure with the improved /Test process which moves - comparisons to the end of Makefile, replaced DIFFNOW=0 with DIFFEND=1. + Update procedure with the + improved process for Test/, which moves comparisons + to the end of Makefile. It replaces DIFFNOW=0 + (which deferred comparisons completely, making the user do them + manually) with DIFFEND=1. Revise and update procedure to keep it in line with current practices as outlined in the Council shared document @@ -35,26 +38,114 @@
TEI Council: Update P5 subset - Rationale -

The Stylesheets tests can succeed only against either the release branch of P5, or the - dev branch of P5, but often not against both simultaneously. For instance, the Stylesheets - dev branch sometimes successfully builds against P5 release, but fails against P5 dev - branch. On release day, we need the Stylesheets release branch to build against P5 release - branch successfully i.e. we need the tests to work with the release branch against the - release branch without producing any errors.

-

Changes on either side (Stylesheets or Guidelines) may break either build. The - Stylesheets test procedure in particular is quite fragile, and if it fails, the build - fails. For instance, since the contents of desc elements are copied over into - schemas, even a small change (like adding a comma) to an element description in the - Guidelines might break the Stylesheets build.

-

Since the Stylesheets are built against the Guidelines, there needs to be a (more or - less) up-to-date copy of the Guidelines in the Stylesheet repository. This copy of the - Guidelines is a file called “p5subset.xml” and it is stored in the source/ - directory. Building the Guidelines in the TEI repository does not - put a new copy of p5subset.xml into the Stylesheets/source/ directory. In - order to keep the version of the p5subset.xml in the Stylesheets repository up to date, - that file is updated monthly by Council members.

+ Rationale +

Many of the Stylesheets’ tests generate schemas from the + TEI Guidelines (using customization ODD files). This means + that the test process needs to have access to a copy of + P5. This in itself is not a particularly big problem — after + all, there is always a copy available at . + But the way many of these tests work is to compare the + schema generated by the test process with the expected + schema: if they are the same, the test succeeds, if there + is a difference, the test fails.

+

On the face of it, this seems a sensible way to test. If + you have changed the Stylesheets, you want to make sure your + changes have not altered the generated schemas, at least not + in a manner you did not expect. But this means there is an + brittle dependency between the Guidelines and the + Stylesheets’ test process, which itself is quite + fragile.

+
+ Dependency +

To understand the dependency problem, imagine that + shortly after the release of P5 version 629.514.13 we drop + the datatype element from the ODD language: the + possible value(s) of an attribute are expressed with a + dataRef rather than a dataRef inside a + datatype. (This means that dataRef would + need to become a member of att.repeatable.) Once we change the + Guidelines so that datatype is not an element, we + need to actually remove datatype from the + Guidelines, so that they remain valid.

+

After these changes, we change the Stylesheets so that + they know how to handle a dataRef, possibly with + minOccurs or maxOccurs, that is a + direct child of attDef. If we try to test the + Stylesheets against P5 v. 629.514.13 (or any previous + version) there will definitionally be no cases of a + dataRef without datatype in the base + ODD, because in that version of the Guidelines a + dataRef was required to be inside a + datatype. So (as long as we did not remove the + code that handles a dataRef inside a + datatype) the Stylesheets tests may not fail, but + neither will they exercise our new code, that which we + most need to test.

+

So we need to tell the Stylesheets to use the new + version of the Guidelines (v. 629.515.0α) as the base + ODD. The way we do this is just to put a copy of the new + version of the Guidelines into the Stylesheets repository.

+
+
+ Fragility +

Because the test procedure involves comparing two + schemas (the actual output generated by the test, and the + output that is expected from the test) using a string + comparison tool, even very minor changes to the + Guidelines may cause a test to fail. In fact, because the + glosses and descriptions of XML constructs are included in + the output schemas (so that tools like oXygen can make use + of them), there are revisions that do not change the actual + XML defined by the schema, but nonetheless will cause a + test to fail.

+

If the description of the + constraint element were corrected from the + formal rules of a constraint to contains + the formal rules of a constraint., every test that + involves creating a schema that contains the + constraint element would fail.

+

If the content model of the + foo element were simplified from + + + + + + + + to just + + + + the same set of documents (those that have two or more + bar elements as children of each foo) + would be valid against the new schema. But since the + actual grammar is different — it now has bar, + bar+ where it used to have bar, bar, + bar*, the test would fail.

+
+
+ Solution +

Since the Stylesheets are tested against a specific + version of the Guidelines, it is very helpful to have a + (more or less) up-to-date copy of the Guidelines in the + Stylesheet repository. If nothing else, this minimizes the + possibility of testing with the wrong version of P5.

+

Thus we store a copy of the Guidelines in a file called + p5subset.xml in the + source/ directory. Just building the Guidelines + in the TEI repository does not put a + new copy of p5subset.xml into the + Stylesheets/source/ directory. The file needs + to be manually copied over, hence these instructions for + doing so. This task is typically performed at least monthly + by a Council member.

+
+
+
Step-by-Step Instructions: Update your local copies of both the TEI and Stylesheets