DevEx: proposal for standard initial install experience

[getify]

Proposed DX Standards for DefraDB Initial Install

The purpose of this item is for members of the DevEx team to lay out aspirational/descriptive direction for the initial installation experience of our tools (specifically DefraDB, but the others, too). We will deliberately not be prescriptive on exactly the means by which we achieve this, as that is better informed by those who are "in the weeds" of the implementation work in DefraDB/etc.

However, we will state that it's our position that this vision represents a "hard requirement" for an initial 1.0 release, to whatever level of practical fidelity is achievable.

Overview

We set the bar that our tooling must be as easy/straightforward to install (or, worst case, compile) as tooling like MongoDB (and SQLite).

Anecdotally, I was able to get a years old "mongodb 5" source distribution from their site archives, and with one dependency update, in 5 minutes I had a compiled and running mongodb 5 instance running on my quite old Debian 9 system. I knew they wouldn't still host a binary distributable for a system that old, but I was pleasantly impressed that the old source code compiled almost immediately out of the box.

Wherever possible, we should have such a delightful experience for our developers/users.

Best Case Path

It should be obvious that the best-case path is for someone to find a pre-built binary/distributable for the tool, targeted to the environment/OS of their choice.

We suggest this would, as tpyical, involve an "N-1" or "N-2" strategy for stable release versions of major platforms (desktop, server, mobile, etc). So for example, support in linux for the Debian distribution would, at time of writing, be for Debian 12 (current stable), Debian 11 (old stable), and ideally even (Debian 10), subject of course to technical requirements.

The "version matrix" for such pre-built distributions should clearly list all major factors that apply in terms of compatibility. In other words, it's not just "Debian 12" but "Debian 12 + ..." where that "..." would detail minimum expectation (or version range) for any dynamically linked resources/tools that are required but not included.

And of course, the more we can distribute (and not rely on users to satisfy themselves), within reason, the better. For example, instead of dynamically linking to something like "libwasmer.so", we could statically link it in the binary distribution, reducing friction for the end-user/end-developer.

The end of installing a binary should ideally include automatically invoking a "setup script" (wizard, etc), the same as make install described below.

Compat/Legacy Build

If possible, in line with the "N-2" strategy of version matrix support, it's helpful to provide a distribution that is explicitly linked/built-with the oldest set of external dependency requirements as possible. For example, in the Debian world, this could be a build against glibc from much older Debians (8.x or 9.x), if practical.

This specifically should be considered a "nice to have" in the overall scheme here, but is important when possible.

Fallback: Compilation

When a developer/user has an environment (incl dependencies) that don't match our official distribution version matrix, the obvious fallback is for them to do their own compilation from source.

However, it's very important that the source not have baked-in assumptions about dependencies that will make it harder for this fallback to actually be utilized. For example, if the "go" module version is declared to be a rather new version, and the we rely on the "auto" behavior of their current go version bootstrapping itself to that higher declared version, there's a minimum go version (1.21, I think?) that this "auto" requires to work. Where possible, we should make sure we have the loosest/most permissive assumptions about these things, to have the widest net cast for developers to make Defra/etc tools work in.

Again, it's very important that we publicly document (in the compilation guides) what these assumptions/minimum requirements are, so that a developer/user landing in this fallback scenario (already a bit of a barrier!) doesn't face a dependency-hell rabbit hole where they just abandon and give up on Defra. We need to let them know in advance, for example: "you must have at least glibc vX.X to proceed".

Configure Script, Make Steps

In line with other tools best practices, our make/etc steps should be well laid-out and clear to understand and progress through. For example:

1. configure -- check all system/env requirements, provide clear messages if anything isn't matched to what make will expect (NOTE: this might not be a required step, up for discussion)
2. make -- with clear and explicit error messages when/if things fail
3. make test -- optional, of course, but always nice for folks who really want to increase their confidence in the fallback path
4. make install -- should invoke a process that gets everything ready to run, including moving binaries where they need to be, setting up config files, ENV settings added to the system, etc; ideally, this might invoke a wizard that steps them through any decisions they need to make to get things initialized and completing the setup
5. make clean (for resetting) -- should actually do the cleaning rather than, as present, just stating the cleaning steps for them to have to do themselves!