Compile .css files in CI rather than checking in compiled files

[Lilith Orion Hafner]

Checking in compiled files is problematic for a few reasons

• It can bloat the repository, especially if the compilation is complex/unstable/hard to delta compress and repeated changes to the source files cause repeated whole-file diffs in the compiled files
• Checked in compiled files pose a higher security risk than checked in source code that is compiled according to checked in compilation instructions. If someone is able to bypass or disable the CI validation, they may be able to check in malicious compiled code without detection whereas if the entire repository is human-readable, it is much harder to inject malware without detection. (This is based on the assumption that it is easier to surreptitiously disable a CI check than to surreptitiously reconfigure a compiler to inject malware)

In the context of the widespread assumption that everything in source control is human readable, this creates a couple additional problems:

• Including non-human readable content in source control can make it harder for new contributors to orient themselves to the codebase by posing a distraction, especially when the files are not binaries but merely obfuscated plaintext (like https://github.com/JuliaDocs/Documenter.jl/blob/f85c4719086fc3c03e2a0792914694e67da9954d/assets/html/themes/documenter-dark.css)
• It makes it harder to get good results from tooling like ag which filter search results to automatically exclude ignored files.
• Changes to compiled files are difficult to review (and if the way to review them is to trust CI to validate them and simply ignore them, then that points to telling git to ignore them instead)

Assuming .scss -> .css compilation and minification is cheap, I propose that minified .css files which are automatically generated from .scss files be removed from source control and instead built at documentation-deployment-time via a package build step. If the generation is substantially more computationally expensive than a download, then artifacts may be a more appropriate solution.

[Morten Piibeleht]

So, I largely disagree with the points above.

• By having users recompile the CSS all the time, we'd be more exposed to attacks against the dependency tree. While that could also affect us here, (1) the attack surface is fixed and much-much smaller, and (2) there is at least some review of the compiled CSS, and the CI check is pretty robust in my opinion.

• Compiling the CSS is not computationally expensive, but you have do deal with additional dependencies. And while Sass.jl would probably be fine as a Documenter dependency nowadays, we may well have to move away from libsass to calling Dart code. (https://sass-lang.com/libsass/ piever/Sass.jl#27)

• One thing I do half-agree on is that the generated files are annoying bloat in the repo, although it's not an issue in practice in my experience. We have a .gitattributes file that declares these files generated, so tooling should take that into account.

  In my mind, the correct way to handle the compiled CSS would be via Artifacts. But I have no clear idea how to manage that end-to-end since, in general, we'd need different artifacts for each commit. We could potentially maintain the theme in a separate repository, but that makes working on any front-end changes quite a bit more annoying.

• One bonus for compiling the theme during makedocs would be that handling custom themes would be slightly easier. But it's also not hard to import DocumenterTools in make.jl if you need that.