Move some docs around

1 files changed, 85 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..235187b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+Biz.Dev is the namespace for business development (duh). Here we define the
+tools and infrastructure for internal dev work.
+
+# Goals of the workflow
+
+- have minimal ceremony
+- default to asynchrony, but allow for synchronous work when necessary
+- automate the boring stuff
+- standardize environments, tooling, and versions to minimize friction
+  while collaborating
+- support the longevity and self-sustainability of the project
+
+Ideally, each contributor should be able to go off grid for a day or a
+week or more, continue working offline, submit their work when finished,
+and have no or minimal conflicts. This also refers to the resilience of
+the production systems.
+
+We should never need "out of office" email auto-replies, or urgent
+contact. No pager duty, no daily stand-ups. Yes, this policy will affect
+what code we write, not just how we write it; that is by design.
+
+# Getting started
+
+Jump into a development shell:
+
+    nix-shell
+
+Then run  `help` to see the dev commands.
+
+# Repository organization
+
+The source tree maps to the module namespace, and roughly follows the
+Haskell namespace hierarchy (although nothing is enforced). The root namespace
+for all code that we own is `Biz`; proprietary applications, products, and
+infrastructure lives under there. Stuff that can be open sourced or otherwise
+externalized should be outside of `Biz`.
+
+Development aspects should be localized to their sub-namespaces as much
+as possible. Only after sufficient iteration such that interfaces are
+solidified and functionality is well-established should some code be
+promoted up the namespace hierarchy.
+
+Start with small namespaces: use `Biz/Thing.hs` before `Biz/Thing/Service.hs`.
+Try to keep all related code in one spot for as long as possible.
+
+Boundaries and interfaces between namespaces should be singular and
+well-defined. Likewise, the functionality and purpose of a particular
+namespace should be singular and well-defined. Follow the unix principle
+of "do one thing and do it well."
+
+Namespaces are always capitalized. I would prefer always lowercase, but
+`ghc` _really_ wants capitalized files, so we appeas `ghc`. In Scheme
+this actually translates quite well and helps distinguish between types
+and values.
+
+File extensions denote _type_ and indicate to the build system how to
+handle the file. So for example:
+
+- `.hs` is Haskell source code, the build system compiles it
+- `.scm` is Scheme source code, ditto
+- `.jnl` is a journal for accounting, the build system will check our
+  balances, make sure we're profitable
+- `.md` for notes and docs, mostly ignored by the build system
+
+# Setting up remote builds
+
+The Biz.Dev machine acts as a remote build server and Nix cache. To use it from
+your local machine, your public key must be at `Biz/Keys/$USER.pub` and your
+user added to `Biz/Users.nix`, then bild will automatically use your key to run
+builds on Biz.Dev.
+
+To use distributed builds for all nix commands, add the following to your NixOS
+configuration:
+
+    nix = {
+      distributedBuilds = true;
+      buildMachines = [
+        {
+          hostName = "dev.simatime.com";
+          sshUser = "yourUserName";
+          sshKey = "/path/to/your/private/key";
+          system = "x86_64-linux";
+        }
+      ];
+    };