Updating_the_Customization_System

Updating the Customization System

There are several [#steps steps] to updating the customization system, although you won't necessarily do all of them for every change. We also have some instructions for [#committing committing or vivifying] changes.

Steps to Update the System

Anchor(steps)

The Matrix questionnaire is a web application that presents a user-linguist with a linguistic-typological questions, and in response to the answers, the customization system creates a LKB-compatible grammar for the language described. When a developer wishes to make changes to the any part of the system, several different parts must all be updated at the same time in order to keep everything working.

The questionnaire is a CGI application written in Python that is stored in the Matrix svn repository (in matrix/gmcs/). Its most important files are:

• The [http://wiki.delph-in.net/moin/matrixdef_File_Syntax matrixdef] file, which defines both the questionnaire and the list of choices -- that is, the name space of attributes and their ranges of values that are used to store the user's answers to the questionnaire.

• matrix.cgi, a CGI script written in Python. The entry point for the questionnaire.

• deffile.py, which defines the MatrixDefFile class. This class is responsible for creating web pages based on the contents of matrixdef.

• choices.py, which defines the ChoicesFile class. This class is responsible for loading, saving, and providing access to the choices file, which contains the user's answers to the questionnaire.

• validate.py, which contains code to confirm that the user's current choices are describe a coherent language. (For example, if the user says the language contains no determiners, they must not have defined one.)

• customize.py, which contains the code that creates an LKB-compatible grammar based on the current choices.

• tdl.py, which defines the TDLFile class.

• Library modules in gmcs/linglib/

When there are changes to be made to the questionnaire, a likely course of action is the following:

1. Form fields for the new choices must be added to the matrixdef file.

   1. If necessary, support for new form field types or behavior (e.g. a drop-down box) must be added to deffile.py.

2. If any old choices have become obsolete, the version number in choices.py (specifically, in the current_version method on the ChoicesFile class) must be incremented. Furthermore, a new up-revving method that converts choices files of version n-1 to the current version n must be added. See the comments in choices.py for details.

3. Install the system to a test location (NOT the live site), then verify the changes look as expected

4. Write appropriate methods in validate.py (or a library's validate() method)

When changes are made to libraries:

1. The linguistic phenomenon to be covered must be identified, along with its range of possible patterns in the world's languages, and based on this range a set of new choices (names and values) must be defined.

2. Write the processing code in customize.py (and/or in a library-specific module)

3. Write [wiki:MatrixCustomizationUnitTesting unit tests] for the code

4. Write [wiki:MatrixRegressionTesting regression tests] to test the output

When changing the underlying infrastructure:

1. Write the changes to matrix.cgi, customize.py, choices.py, or whatever module is needing change

2. Definitely write [wiki:MatrixCustomizationUnitTesting unit tests] for these kinds of changes

3. Update the documentation as necessary (e.g. these wiki pages)

Don't forget to [#committing commit] the changes.

Committing and Vivifying Changes

Anchor(committing)

1. svn update

2. resolve conflicts

3. run the regression tests: MatrixRegressionTesting

4. fix any regressions (repeat as necessary)

5. svn diff each file to find diffs and note in text file for svn comment

6. svn update

7. svn commit Vivify to the live site with the following command:

python matrix.py vivify