|
| 1 | +A couple of notes for people interested in contributing |
| 2 | + |
| 3 | +# Adding new features |
| 4 | +There are many PDF features which have only been introduced at a specific version. In addition to that, some PDF |
| 5 | +features are also restricted to specific sub-standards of PDF, like PDF/UA. Because of this, we need to be careful |
| 6 | +when adding such new features that they are no in violation of that. In particular, in case a feature is only available |
| 7 | +for a specific version, you need to add a check in the code so that it's only used when the current version we are exporting |
| 8 | +to supports it. |
| 9 | + |
| 10 | +In `crates/krilla/src/validation`, you can find some documentation on each of the validated export modes, as well as |
| 11 | +all the requirements needed to fulfill it, and how Typst fulfills them. So if you don't have access to the original |
| 12 | +specification documents, you should check those files to see whether they appear in it, and if so add appropriate checks |
| 13 | +to make sure we do not produce documents violating some of the standards. |
| 14 | + |
| 15 | +# Testing |
| 16 | +As mentioned in the README, krilla has two kinds of tests: snapshot tests and visual regression tests. |
| 17 | +You can create such tests by annotating your tests with the corresponding attributes (see the existing |
| 18 | +tests for some examples). The macros are currently somewhat undocumented and not very cleanly implemented, |
| 19 | +but you should be able to find everything you need by looking at examples of existing tests. |
| 20 | + |
| 21 | +By default, if you run `cargo test`, only the snapshot tests will be run, all visual regression tests will |
| 22 | +be skipped. This should hopefully be enough for most cases, as running the visual regression tests requires |
| 23 | +a very specific setup on your computer. |
| 24 | + |
| 25 | +If you really do need to run the visual regression tests, you can run |
| 26 | +`VISREG="" cargo test`. `krilla` uses my own small library called `sitro` (https://github.com/LaurenzV/sitro) that |
| 27 | +I built for this purpose to render PDFs, which basically is an abstraction over different PDF viewers and allows |
| 28 | +rendering PDF to bitmap images. However, the prerequisite is that you have the programs installed on your system and |
| 29 | +set the corresponding environment variables. You can take a look at the `ci.yml` file to see what the basic necessary |
| 30 | +setup is. On MacOS systems, you need to build another additional program that uses Quartz to render PDFs. See the README |
| 31 | +of `sitro` for more information on how to do that. As you can imagine, setting this up is quite a pain, but hopefully, |
| 32 | +for most cases it should be enough to just run the snapshot tests. |
| 33 | + |
| 34 | +In addition to that, you can prepend `SKIP_SVG` to skip the SVG-related visual regression tests. You can prepent |
| 35 | +`REPLACE` to overwrite the currently existing references images/snapshots, and you can use `STORE` to store the |
| 36 | +final PDF version of each tests in the `store` directory, which makes it easier to manually inspect them. |
0 commit comments