Documenting project/technical philosophy

[getify]

Figured I should explicitly write out several things that may be helpful to reference in terms of technical decision making going forward:

1. I'm NOT going to act as a dictator (BDFL) for this project. Right now I'm the main/only core maintainer, and I own the server (and paid for the domain and SSL certs and upgraded DNS + DNSSEC). But those are, in my mind, temporary conditions that currently place me in a more authoritative role. Over time, I expect and hope that others will be promoted to core maintainer status, and as that happens, I fully expect to share decision making and even to defer to others on certain matters. So please don't think that I'm going to hold an iron grip over this project. I see myself as shepherd right now, and I will protect and fight for what I think is right, but over time, what's right is that it won't be only me doing so.

2. I hold a firm stance and belief that complexity of systems has to be fought at the individual decision level, and that means deciding to use restraint in including tools and processes unless and until those can be fully justified. There've already been a few conversations of that sort, such as discussion over using linter/style-formatter tooling (deferred for now, perhaps revisited later).

   I've also taken some criticism/disagreement in social media over publicly stating that the app won't be built on top of frameworks (like React/Vue/etc). I firmly believe apps should be built with the least technology necessary to accomplish the task. I'm not even remotely convinced either the app's complexity, or the complexity of our contributor organization/skills, will justify using a framework. That fits with my general feeling that most apps these days, even SPAs, don't actually need these tools, and that they're chosen more to prioritize dev UX and not to fit the actual technical needs of the system being designed. Will this app ever use those? I doubt it, but it's not impossible.

   I have a number of libraries I've authored, which I would LOVE to showcase in this project. But I haven't even remotely considering bringing any of them in. As much as I'd love to use the coding styles/approaches they enable, and as much as I'd love to be able to show off why I think they're awesome (they are!), that's not what is best for THIS project.

   Why? Because privacy/security/safety are THE MOST IMPORTANT FEATURE, period. End of story. The increase in surface area for the code this app uses exponentially increases the risks, especially as it relates to proper security auditing (hopefully by independent parties eventually). It also harms general developer readability to have more code in the code base than is strictly necessary, since that's more to read, more to learn, more to understand.

   I don't judge the supposed developer productivity increases of using popular frameworks/libraries/tools like that, to outweigh the importance of minimizing, wherever possible, what code exists in this app, and certainly what "third party" code is included. Plain and simple. My libraries aren't going to be used (probably), and other frameworks and libraries also aren't going to be used (probably).

   The few exceptions we make, to include third party code, will be deliberate and will have strong justification, not simply preferences. Right now, I already made the call to include three: idbKeyval (a very well known and super visible and trusted cross-browser tool for ironing out complications with storing data in indexDB), hash-wasm (specifically, the wasm build of the argon2 password-hashing algorithm), and base64-arraybuffer, a small but important chunk of code for efficiently AND CORRECTLY handling conversion of data to/from base64 string representation and binary array buffers (used in encryption/decryption). Why these 3? Because getting them wrong (by doing them ourselves) actually undermines the main principles of the app: privacy/safety/security. Since that's so important, and since the areas are so sensitive and difficult to get right, I judge that these 3 tiny libraries meet the bar necessary to be included.

3. The app is client-side only, and will remain that way with no stateful server (only stateless static file serving, with some important tweaks for security headers), despite how nice some server-enabled features might be (for devs and for users), UNLESS AND UNTIL we can justify such a (huge) inflection point change. I've got a running list of things a server could do for us, if we ever decide to cross that line, and we can discuss the merits and weigh things. But the default position is, this app runs client-only, and that user data is always encrypted and always local-only on their device. That fits with the main principles of the app, and is therefore how I justify such a position.

4. The app is using web technology on purpose, even though in some respects it would be better for the app if it were built with fully native technologies (Java, Swift/Obj-C, etc).

   Why? Because I deem the value of view-source for this app to be of sufficient importance to the overall project principles to override the arguments to the contrary. It's not enough, in my mind, that this app be open-source. It must be able to be audited, on any device, to guarantee and prove that it does what we say it does, no more, no less. Users cannot audit their native apps like that, but they CAN audit web apps. So we will embrace that.

   That leads to another perhaps surprising decision: we will not transpile, bundle, minify, or otherwise obfuscate any of the JS code of this app (other than including any third-party tools as previously discussed, in their distributed forms). Again, why? Because we are prioritizing lowering the barrier to being able to see, audit, and prove what this app is doing, and excluding from concern anything that it's not doing.

   NOTE: gzip compression is fine, and will be used, as it simply reduces bandwidth costs and serves the user better by increasing the initial install/load performance. But we'll be gzipp'ing fully open and readable JS code and delivering that to the browser. No funny business with source maps where the code running is even slightly different than the code the user or developer sees in the browser tools.

5. This app will be offline by default (again, client only), performant by default, and accessible by default. We will use, where appropriate, basic but important accessibility affordances in building this app, including but not limited to:

   • semantic HTML, native HTML form elements, alt-text on images, CSS for its intended/native purposes, etc
   • HTML aria attributes, like "role", "aria-label", "aria-live", "aria-atomic", etc
   • proper color contrast (see https://contrast-ratio.com and other similar tools)
   • keyboard, pointer, and other appropriate input events that are by default more accessible
   • etc

---

I will probably add more to this list as we go along, but hopefully this helps shed some light on the philosophies/principles I will be using in guiding the technical decision making of this project.

I welcome any and all input/feedback on these philosophies. I promise to listen to and respect dissent, but I don't necessarily promise to change these principles unless and until it becomes clear and justified to do so.