-
-
Notifications
You must be signed in to change notification settings - Fork 3.8k
Quality Control
We love the CSL style repository, and wish to keep it in tip-top shape. Since we have thousands of styles and hundreds of contributors, we rely heavily on automated quality control and periodic maintenance. This page describes our best practices.
The "master" branch of the style repository stores the styles for the most recent CSL release. To allow changes to be reviewed before they end up in "master", we try to avoid committing changes directly to "master" as much as possible.
Instead, we rely heavily on forks, branches, and pull requests. Only our maintainers have direct commit access to the repository. Contributors can fork the repository, make their changes in their copy of the repository (ideally in a branch), and create a pull request. This allows us to review your changes, and merge them into the official repository.
Travis CI is a so-called Continuous Integration service that runs a series of checks on every commit made to the "master" branch, and on every commit in incoming pull requests. Each Travis test run is called a "build".
If Travis doesn't detect any problems in your pull request, it will report that the build passed. Otherwise the build fails, and you will find a link to the build report that shows which tests failed. Add a new commit to your pull request, and Travis will start a new build and run all tests again. Only pull requests that pass all the Travis tests can be accepted into the repository.
The tests are stored in the style repository itself. Among other things, they make sure that:
- there are no styles with the same file name, title, or ISSN
- all styles are named correctly, and have style IDs and "self" links matching the file names
- all styles validate against the CSL schema
- all styles have the correct license
- all "template" and "independent-parent" links point to existing independent styles
- all style macros are defined and used
- the root directory contains all independent styles, and the "dependent" subdirectory all dependent styles
It is possible to run the tests locally on your computer, which is especially useful to frequent contributors.
To keep styles consistently formatted, we manually run a Python script every few weeks or so. The script does the following:
- reindent the XML code, using 2 spaces per indentation level
- put the elements in the
</info>section in a standard order - escape characters that are hard to identify by eye (such as the various dashes and spaces)
Every so often, we also manually run a bash script that validates the styles against a customized CSL schema that is extra strict, and includes requirements specific to our repository.
Here we keep track of problematic CSL code patterns we have observed in the wild, and provide information on how they can be detected and corrected.
If the second field in the bibliography is flushed, then it should not have a space as a prefix.
Search patterns
<bibliography[^>]*second-field-align="flush"[^>]*>.*<layout[^>]*>\r\n\s*<text variable="citation-number"[^>]*/>\r\n\s*<text[^>]*prefix=" "
Fix
Delete prefix=" " by hand, but it seems possible to automatically delete the last prefix attribute in this pattern. No, critical case found. Moreover, no case with a different prefix beginning with a space found.
History
2015-01: #1349 and #1346 : ca. 39 matches
Search Pattern
<[^/>]*suffix="[^"/>]* "[^/>]*/?>\s*\r\n\s*<[^/>]*prefix=" [^"/>]*"[^/>]*/?>
Fix
Manually look at every case and either (i) delete the space in suffix, (ii) delete the space in the prefix, (iii) use a group with delimiter=" ", or (iv) rewritte some parts of the style. This can take some time in order to not change the punctation. It may be possible to restrict the search pattern more, in order to obtain smaller sets of the same/similar replacements.
History
2015-01: #1301 : ca. 300 hits in 230 files