From b1468fd5630a01966c9c3243de6c7882c3c95b7a Mon Sep 17 00:00:00 2001 From: Ben Sima Date: Mon, 16 Nov 2020 14:02:37 -0500 Subject: add build badge and move some docs around --- Biz/Dev.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 Biz/Dev.md (limited to 'Biz') 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 -- cgit v1.2.3