From 24e4c3a19b92540b742c29b4790694dacde8a288 Mon Sep 17 00:00:00 2001 From: Julian Ospald Date: Sun, 12 Apr 2020 19:48:26 +0200 Subject: [PATCH] Add HACKING.md --- HACKING.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 HACKING.md diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 0000000..59179e6 --- /dev/null +++ b/HACKING.md @@ -0,0 +1,29 @@ +# HACKING + +## Design decisions + +### Using [Excepts](https://hackage.haskell.org/package/haskus-utils-variant-3.0/docs/Haskus-Utils-Variant-Excepts.html) as a beefed up ExceptT + +This is an open variant, similar to [plucky](https://hackage.haskell.org/package/plucky) or [oops](https://github.com/i-am-tom/oops) and allows us to combine different error types. Maybe it is too much and it's a little bit [unergonomic](https://github.com/haskus/packages/issues/32) at times. If it really hurts maintenance, it will be removed. It was more of an experiment. + +### No use of filepath or directory + +Filepath and directory have two fundamental problems: 1. they use String as filepath (see [AFPP](https://gitlab.haskell.org/ghc/ghc/-/wikis/proposal/abstract-file-path) as to why this is wrong) and 2. they try very hard to be cross-platform at the expense of low-level correctness. Instead, we use the [hpath](https://github.com/hasufell/hpath) libraries for file and filepath related stuff, which also gives us stronger filepath types. + +### No use of haskell-TLS + +I consider haskell-TLS an interesting experiment, but not a battle-tested and peer-reviewed crypto implementation. There is little to no research about what the intricacies of using haskell for low-level crypto are and how vulnerable such binaries are. Instead, we use either curl the binary (for FreeBSD and mac) or http-io-streams, which works with OpenSSL bindings. + +### Optics instead of lens + +They're a little safer (less Monoid weirdness with view) and have better error messages. Consider: `view (_Just . to (++ "abc")) Nothing` (lens) vs `view (_Just % to (++ "abc")) Nothing` (optics). The latter does not compile (good). + +### Strict and StrictData on by default + +Kazu Yamamoto [explained it in his PR](https://github.com/yesodweb/wai/pull/752#issuecomment-501531386) very well. I like to agree with him. The instances where we need non-strict behavior, we annotate it. + +## Code style and formatting + +1. Brittany +2. mtl-style preferred +3. no overly pointfree style