|
| 1 | +# CSL Style Quality Control |
| 2 | + |
| 3 | +We love the CSL style repository, and wish to keep it in tip-top shape. |
| 4 | +Because we have thousands of styles and hundreds of contributors, we rely heavily on automated quality control and periodic maintenance. |
| 5 | +This page describes our best practices. |
| 6 | + |
| 7 | +## Forks and Pull Requests |
| 8 | + |
| 9 | +The "master" branch of the style repository stores the styles for the most recent CSL release. |
| 10 | +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. |
| 11 | + |
| 12 | +Instead, we rely heavily on forks, branches, and pull requests. |
| 13 | +Only our maintainers have direct commit access to the repository. |
| 14 | +Contributors can fork the repository, make their changes in their copy of the repository (ideally in a branch), and create a pull request. |
| 15 | +This allows us to review your changes, and merge them into the official repository. |
| 16 | + |
| 17 | +## Travis CI |
| 18 | + |
| 19 | +[Travis CI](https://travis-ci.org/) is a 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. |
| 20 | +Each Travis test run is called a "build". |
| 21 | + |
| 22 | +If Travis doesn't detect any problems in your pull request, it will report that the build passed. |
| 23 | +Otherwise the build fails, and you will find a link to the build report that shows which tests failed. |
| 24 | +Add a new commit to your pull request, and Travis will start a new build and run all tests again. |
| 25 | +Only pull requests that pass all the Travis tests can be accepted into the repository. |
| 26 | + |
| 27 | +The tests are stored in the style repository itself. |
| 28 | +Among other things, they make sure that: |
| 29 | + |
| 30 | +* there are no styles with the same file name, title, or ISSN |
| 31 | +* all styles are named correctly, and have style IDs and "self" links matching the file names |
| 32 | +* all styles validate against the CSL schema |
| 33 | +* all styles have the correct license |
| 34 | +* all "template" and "independent-parent" links point to existing independent styles |
| 35 | +* all style macros are defined and used |
| 36 | +* the root directory contains all independent styles, and the "dependent" subdirectory all dependent styles |
| 37 | + |
| 38 | +It is possible to [run the tests locally](#Test-Environment) on your computer, which is especially useful to frequent contributors. |
| 39 | + |
| 40 | +## Indentation, Ordering, and Escaping |
| 41 | + |
| 42 | +To keep styles consistently formatted, we manually run a [Python script](https://github.com/citation-style-language/utilities/blob/master/csl-reindenting-and-info-reordering.py) every few weeks or so. |
| 43 | +The script does the following: |
| 44 | + |
| 45 | +* reindent the XML code, using 2 spaces per indentation level |
| 46 | +* put the elements in the `</info>` section in a standard order |
| 47 | +* escape characters that are hard to identify by eye (such as the various dashes and spaces) |
| 48 | + |
| 49 | +## Extra-strict Validation |
| 50 | + |
| 51 | +Every so often, we also manually run a [bash script](https://github.com/citation-style-language/utilities/blob/master/style-qc.sh) that validates the styles against a [customized CSL schema](https://github.com/citation-style-language/schema/blob/master/csl-repository.rnc) that is extra strict, and includes requirements specific to our repository. |
| 52 | + |
| 53 | +## Repairing Problematic Code Patterns |
| 54 | + |
| 55 | +_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._ |
| 56 | + |
| 57 | +### Superscript on citation-number instead of whole citation |
| 58 | + |
| 59 | +In numeric styles where superscripted numbers are used, it's important to superscript the entire citation so that any punctuation is also superscripted, and e.g. use: |
| 60 | + |
| 61 | +```xml |
| 62 | +<layout delimiter="," vertical-align="sup"> |
| 63 | + <text variable="citation-number"/> |
| 64 | +</layout> |
| 65 | +``` |
| 66 | + |
| 67 | +instead of: |
| 68 | + |
| 69 | +```xml |
| 70 | +<layout delimiter=","> |
| 71 | + <text variable="citation-number" vertical-align="sup"/> |
| 72 | +</layout> |
| 73 | +``` |
| 74 | + |
| 75 | +**History** |
| 76 | + |
| 77 | +2016-10: [#2256](https://github.com/citation-style-language/styles/issues/2256) : 47 hits |
| 78 | + |
| 79 | +### Spaces if second field is flushed |
| 80 | + |
| 81 | +If the second field in the bibliography is flushed, then it should not have a space as a prefix. |
| 82 | + |
| 83 | +**Search patterns** |
| 84 | + |
| 85 | + <bibliography[^>]*second-field-align="flush"[^>]*>.*<layout[^>]*>\r\n\s*<text variable="citation-number"[^>]*/>\r\n\s*<text[^>]*prefix=" " |
| 86 | + |
| 87 | +**Fix** |
| 88 | + |
| 89 | +Delete `prefix=" "` by hand, but it seems possible to automatically delete the last prefix attribute in this pattern. |
| 90 | +No, critical case found. |
| 91 | +Moreover, no case with a different prefix beginning with a space found. |
| 92 | + |
| 93 | +**History** |
| 94 | + |
| 95 | +2015-01: [#1349](https://github.com/citation-style-language/styles/pull/1349) and [#1346](https://github.com/citation-style-language/styles/pull/1346) : ca. 39 matches |
| 96 | + |
| 97 | + |
| 98 | +### Adjacent spaces from suffix and prefix |
| 99 | + |
| 100 | +**Search Pattern** |
| 101 | + |
| 102 | + <[^/>]*suffix="[^"/>]* "[^/>]*/?>\s*\r\n\s*<[^/>]*prefix=" [^"/>]*"[^/>]*/?> |
| 103 | + |
| 104 | +**Fix** |
| 105 | + |
| 106 | +Manually look at every case and either |
| 107 | + (i) delete the space in suffix, |
| 108 | + (ii) delete the space in the prefix, |
| 109 | + (iii) use a group with `delimiter=" "`, or |
| 110 | + (iv) rewritte some parts of the style. |
| 111 | +This can take some time in order to not change the punctation. |
| 112 | +It may be possible to restrict the search pattern more, in order to obtain smaller sets of the same/similar replacements. |
| 113 | + |
| 114 | +**History** |
| 115 | + |
| 116 | +2015-01: [#1301](https://github.com/citation-style-language/styles/issues/1301) : ca. 300 hits in 230 files |
| 117 | + |
| 118 | + |
| 119 | +## Test Environment |
| 120 | + |
| 121 | +[](http://travis-ci.org/citation-style-language/styles) |
| 122 | + |
| 123 | +To maintain the quality of the styles in the official repository, we have set up an environment for quality-control testing in the repository's [master branch](https://github.com/citation-style-language/styles/tree/master). |
| 124 | +After every commit to this branch, the tests will be executed on [Travis CI](http://travis-ci.org/#!/citation-style-language/styles) in order to alert us should new (or newly updated) styles break any of the quality control rules. |
| 125 | + |
| 126 | +If you are a style author, maintainer or would like to contribute to an existing style, you are advised to install the test environment on your computer in order to run the tests while you're working on a style and to make sure all tests are still passing before you commit any changes to the repository. |
| 127 | + |
| 128 | +### Installation |
| 129 | + |
| 130 | +Before installing the test environment, please make sure that Ruby is available on you computer. |
| 131 | +If Ruby is not installed, please follow the [official instructions](http://www.ruby-lang.org/en/downloads/) on how to install it on your operating-system. |
| 132 | +The test environment should work on all current releases of Ruby and is backwards compatible with version 1.8.7. |
| 133 | +Some of our tests involve RelaxNG schema validation; these tests are based on [libxml](http://www.xmlsoft.org/) via [Nokogiri](http://nokogiri.org/). |
| 134 | +Please see these [operating-system specific instructions](http://nokogiri.org/tutorials/installing_nokogiri.html) if you have any problems installing the test setup because of these requirements. |
| 135 | + |
| 136 | +**Note: it seems in Ruby 1.8.7 you can get some failures with [] and {} comparison failing** |
| 137 | + |
| 138 | +Once Ruby is installed on your computer, it is easy to setup the test environment. |
| 139 | +First, clone into the official repository (if you have previously cloned the repository you can skip this step): |
| 140 | + |
| 141 | + $ git clone https://github.com/citation-style-language/styles.git |
| 142 | + $ cd styles |
| 143 | + |
| 144 | +You should work directly on the master branch. |
| 145 | + |
| 146 | +Next, we will install all requirements using [Bundler](http://gembundler.com/) (run `[sudo] gem install bundler` to make sure you have the latest version installed). |
| 147 | +Please note that depending on how Ruby is installed on your system you might need administrator privileges to install Ruby Gems, therefore, we have prefixed the commands with an optional `[sudo]`: |
| 148 | + |
| 149 | + $ [sudo] bundle install |
| 150 | + |
| 151 | +### Usage |
| 152 | + |
| 153 | +Once your bundle is installed there are two ways to run the tests. |
| 154 | +You can use rake: |
| 155 | + |
| 156 | + $ rake |
| 157 | + |
| 158 | +Or you can run the tests using `rspec`: |
| 159 | + |
| 160 | + $ bundle exec rspec spec |
| 161 | + |
| 162 | +The latter is useful if you would like to pass special parameters. |
| 163 | +For example, if your Terminal does not support colors, the output may be illegible. |
| 164 | +In this case try running the tests with: |
| 165 | + |
| 166 | + $ bundle exec rspec spec --no-color |
| 167 | + |
| 168 | +Or, if you would like a more verbose output of all tests, you can switch to a different format, for example: |
| 169 | + |
| 170 | + $ bundle exec rspec spec --format documentation |
| 171 | + |
| 172 | +Will print a summary of all tests for each style. |
| 173 | + |
| 174 | +#### Testing styles in isolation |
| 175 | + |
| 176 | +With the growing number of styles and tests available in the repository the number of test cases to execute has risen into the range of 100,000 – for obvious reasons, execution may take up to a few minutes on your computer. |
| 177 | +In order to allow for quicker feedback-loops when working on styles, you can set the environment variable CSL_TEST to control which styles to include in the test. |
| 178 | + |
| 179 | +The CSL_TEST variable may contain a list of file names (separated by spaces) of styles to include; |
| 180 | +please note that the name should be the file's full base-name including the '.csl' extension. |
| 181 | +However, for additional flexibility, you can include regular expression wildcards as well. |
| 182 | + |
| 183 | + $ CSL_TEST="apa.csl vancouver.csl" bundle exec rspec spec |
| 184 | + |
| 185 | + $ CSL_TEST="chicago.*" bundle exec rspec spec |
| 186 | + |
| 187 | +Finally, you can set the CSL_TEST variable to the special value 'git'; |
| 188 | +by doing that you can limit the styles to be included in the test run to those styles which are currently marked as modified in your local git repository. |
| 189 | + |
| 190 | + $ CSL_TEST="git" bundle exec rspec spec |
| 191 | + |
| 192 | +#### Windows |
| 193 | + |
| 194 | +For colored output of the test results on Windows, [see this guide](http://softkube.com/blog/ansi-command-line-colors-under-windows/). |
0 commit comments