diff options
| -rw-r--r-- | Biz.md | 18 | ||||
| -rw-r--r-- | Biz/Dev.md | 58 | ||||
| -rw-r--r-- | README.md | 38 |
3 files changed, 59 insertions, 55 deletions
@@ -5,21 +5,3 @@ 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. - -## 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. 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 @@ -1,38 +1,2 @@ -Jump into a development shell: +[](https://builds.sr.ht/~ben/biz/commits/.build.yml?) - 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 |