diff options
| -rw-r--r-- | README.md | 123 |
1 files changed, 89 insertions, 34 deletions
@@ -1,7 +1,25 @@ -Omni.Dev is the namespace for development. Here we define the tools and -infrastructure for internal dev work. +This repo is for all subprojects. -# Goals of the workflow +# Goals of this project + +The Omni project is to leverage automation and asymmetries to create wealth. The +target of the wealth is Bitcoin. The means: write everything down, first +in English, then in code. + +Resources defined in the repo can be used to quickly create and release +products. New technology shall be prototyped and developed as needed. + +Since Bitcoin always goes up, as long as we are acquiring more Bitcoin, then we +are growing our wealth. There is a limit to the amount of wealth that one person +needs, roughly defined as how much is required to live a modest life and provide +for one's family. Once this is achieved, excess wealth shall be deployed to +improve the world through activist entrepreneurship. + +# Developer Guide + +Here we define the tools and infrastructure for all dev work. + +## Goals of the workflow - have minimal ceremony - default to asynchrony, but allow for synchronous work when necessary @@ -19,53 +37,90 @@ 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: +## Source Layout - nix-shell +The source tree maps to the module namespace, and roughly follows the Haskell +namespace hierarchy. This is true of all languages: Python, Scheme, Rust, C, +etc. -Then run `help` to see the dev commands. +Namespaces are formatted either as file paths, like `Omni/Dev`, or +dot-separated, like `Omni.Dev`. Parts of the namespace should always be +capitalized. -# Repository organization +The namespace for all products that we own is `Biz`, this includes proprietary +applications, products, and related infrastructure. -The source tree maps to the module namespace, and roughly follows the Haskell -namespace hierarchy (although nothing is enforced). +The `Omni` namespace is used for internal development tooling and infrastructure +that are shared between all other projects. -The namespace for all products that we own is `Biz`; proprietary applications, -products, and related infrastructure lives under there. The `Omni` namespace is -used for internal development tooling and infrastructure that are not related to -individual products. Stuff that can be open sourced or otherwise externalized -should be outside of `Biz` or `Omni`. +Stuff that can be open sourced or otherwise externalized should be outside of +`Biz` or `Omni`. -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. +Related code should be kept close together. This means that you should start +with small namespaces: use `Omni/Thing.hs` before `Omni/Thing/Service.hs`. Try +to keep all related code in one spot for as long as possible. -Start with small namespaces: use `Omni/Thing.hs` before `Omni/Thing/Service.hs`. -Try to keep all related code in one spot for as long as possible. +Re-use code from the `Omni/` namespace as much as possible. For example, use +`Omni/Cli.hs` or `Omni/Test.py` instead of trying to roll your own code for cli +parsing or running test suites. If the the namespace doesn't have the feature +you need, then add the feature. 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 and Python this -actually translates quite well and helps distinguish between types/classes and -values. +Namespaces are always capitalized. In Scheme and Python this actually translates +quite well and helps distinguish between types/classes/modules and values. + +## Available tools + +We provide some tools for working with projects in the omnirepo: + +### bild + +`bild` is our universal build tool. It can build and test everything in the repo. + +#### Examples + +`bild --test Omni/Bild.hs` will build and test the `Omni/Bild.hs` namespace. Use +this command to run tests for a namespace. + +`bild --time 0 Omni/Cloud.nix` will build the `Omni/Cloud.nix` namespace, which +is our cloud VM instance. The `--time 0` argument disables the timeout (which +defaults to 10 minutes), this is useful for longer builds. + +`bild --json Omni/Test.hs` this just does the analysis step, and prints a +description of the build as JSON. It will not build anything. + +### lint + +The `lint` command is a universal lint and formatting tool. It will error if any +lints fail, or if the code is not formatted properly. Use `lint --fix` to +autofix any lints or autoformat where possible. + +#### Examples + +`lint Omni/Cli.hs` will lint the `Omni/Cli.hs` namespace and report any errors. + +`lint --fix **/*.py` will lint and fix all Python files in the repo. + +### repl.sh + +This is like `nix-shell` but specific to our repo. It will analyze the given +namespace, pull in all necessary dependencies, and start a bash shell or +language-specific repl. + +#### Examples -File extensions denote _type_ and indicate to the build system how to -handle the file. So for example: +`repl.sh Omni/Bild.hs` this creates a nix shell for the `Omni/Bild.hs` +namespace, and starts a Haskell repl using `ghci` with the namespace already +loaded. -- `.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 +`repl.sh --bash Omni/Log.py` this creates a nix shell for `Omni/Log.py`, but +starts a bash shell for the namespace instead of a Python repl. -# Setting up remote builds +## Setting up remote builds The `Omni.Dev` machine acts as a remote build server and Nix cache. To use it from your local machine, your public key must be at `Omni/Keys/$USER.pub` and your |