diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..0c4165d --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,49 @@ +# Architecture + +## Fetching Crate Info + + + +## Diffing Crates + + + + +## Deployment + +The workflow for deployment work like this: + +- Building the frontend using `trunk build --release` +- Compressing assets using `gzip` and `brotli` +- Adding a `_redirects` file to configure it as a single-page application + +![Deployment diagram](deployment.svg) + +Building is done using [Trunk][trunk]. It uses Cargo under the hood to compile +the code for `wasm32-unknown-unknown`, adds some glue code to launch it in the +browser and links the assets. Running this includes: + +- Running `tailwindcss` to generate the Tailwind CSS styles. +- Using [wasm-bindgen][] to generate bindings for the WebAssembly binary for the browser. +- Using [wasm-opt][] to optimize the resulting WebAssembly binary. +- Including the assets and hashing them for Sub-Resource Integrity and cache busting +- Minifying the assets + +Deployment is done using [GitLab CI][gitlab-ci]. The +[configuration](../.gitlab-ci.yml) runs Trunk, and uses `gzip` and `brotli` to +pre-compress the files. Using compression makes the resulting WebAssembly blob +and assets significantly smaller, at the time of writing, it makes it go from +3MB to 1MB. This step consists of: + +Hosting of the project is provided by [GitLab Pages][gitlab-pages]. The +resulting files of the building and compression are statically hosted by it. +GitLab Pages will serve the precompressed files if the request indicates that +the client supports it. A `_redirects` file is used to tell it to serve the +`index.html` file for every route, to make it work as a single-page +application. + +[trunk]: https://trunkrs.dev/ +[gitlab-pages]: https://docs.gitlab.com/ee/user/project/pages/ +[gitlab-ci]: https://docs.gitlab.com/ee/ci/ +[wasm-opt]: https://github.com/WebAssembly/binaryen +[wasm-bindgen]: https://github.com/rustwasm/wasm-bindgen diff --git a/docs/deployment.svg b/docs/deployment.svg new file mode 100644 index 0000000..977951b --- /dev/null +++ b/docs/deployment.svg @@ -0,0 +1,4 @@ + + + +
Source Code
diff.rs repository
Build
trunk build 
--release
uncompressed files
Build Output
dist/ folder
GZip Compression
gzip -vk *
Brotli Compression
brotli -vk *
Build Output with Compressed Assets
dist/ folder
GitLab Pages
https://diff.rs
Redirects Config
_redirects file
 \ No newline at end of file diff --git a/docs/maintenance.md b/docs/maintenance.md new file mode 100644 index 0000000..2f7e3c5 --- /dev/null +++ b/docs/maintenance.md @@ -0,0 +1,27 @@ +# Maintenance + +These are maintenance tasks that should be performed regularly. Anyone can +perform these and create a pull request. These actions should only be performed +if they don't break anything, it's okay for `diff.rs` to be a few versions +behind if there are bugs that prevent it from upgrading to newer tool or +dependency versions, unless there are security issues. + +## Update Tool Versions + +- Update Rust version in `rust-toolchain.toml` to latest +- Update tool versions in `Trunk.toml` to latest +- Update Trunk version to latest in `.gitlab-ci.yml` + +## Update Dependency Versions + +- Use `cargo update` to update pinned version dependencies +- Use `cargo outdated` to see if there are newer versions of dependencies and manually upgrade + +## Testing + +To test if the changed work, simply serve the page with `trunk` and test it +locally (in a browser) to see if it still works with the changes. + + trunk serve --release + +