From 32a13c8941538fd38d91091f99efe79baacb700f Mon Sep 17 00:00:00 2001 From: Ben Sima Date: Wed, 1 Dec 2021 08:38:28 -0500 Subject: Move some docs around --- Biz.md | 7 ----- Biz/Dev.md | 86 -------------------------------------------------------------- README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 85 insertions(+), 93 deletions(-) delete mode 100644 Biz.md delete mode 100644 Biz/Dev.md create mode 100644 README.md diff --git a/Biz.md b/Biz.md deleted file mode 100644 index 5fef2b2..0000000 --- a/Biz.md +++ /dev/null @@ -1,7 +0,0 @@ -# Biz - -The end is financial independence. The means: write everything down, -first in English, then in code. Automate it until we don't have to work -any longer. - -Compounding returns are magical. Wealth is found in asymmetries. diff --git a/Biz/Dev.md b/Biz/Dev.md deleted file mode 100644 index 0061db3..0000000 --- a/Biz/Dev.md +++ /dev/null @@ -1,86 +0,0 @@ -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 -- `.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 - -# 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"; - } - ]; - }; 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"; + } + ]; + }; -- cgit v1.2.3