Skip to content

Commit 5d17b09

Browse files
committed
Add contributer notes
1 parent ffdd1aa commit 5d17b09

File tree

1 file changed

+36
-0
lines changed

1 file changed

+36
-0
lines changed

CONTRIBUTING.md

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
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

Comments
 (0)