add build badge and move some docs around

1 files changed, 58 insertions, 0 deletions

diff --git a/Biz/Dev.md b/Biz/Dev.md
new file mode 100644
index 0000000..0341db1
--- /dev/null
+++ b/Biz/Dev.md
@@ -0,0 +1,58 @@
+# 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.
+
+The source tree maps to the module namespace, and roughly follows the
+Haskell namespace hierarchy (although nothing is enforced). The main
+'common' space is `Biz`, other namespaces should be related to their
+application.
+
+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.
+
+Boundaries and interfaces between namespaces should be small and
+well-defined. Likewise, the functionality and purpose of a particular
+namespace should be small and well-defined. Following the unix principle
+of "do one thing and do it well" is advised.
+
+For building the code, we use `nix` and basically copy the namespace
+hierarchy into the main build file `./default.nix`.
+
+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
+- `.org` is an organizational text document, the build system ignores
+  this, but we use them to make plans and such
+- `.jnl` is a journal for accounting, the build system will check our
+  balances, make sure we're profitable