diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 66 |
1 files changed, 25 insertions, 41 deletions
@@ -1,40 +1,27 @@ -# Source layout +# Source Layout - aero browser apps, compiled with ghcjs - apex server-side api stuff, compiled with ghc - bild temporary storage for build artifacts - chip executable scripts in python, bash - depo for deployment, machine-specific nix code - lore shared libraries, compiled with either ghc/js - mode nixos modules; services and modular config - pack nix packages & external packages that we import - soar s3/spaces assets, like images, via git-annex +The source tree maps to the DNS namespace that we own. The purpose of this +mapping is to keep things organized hierarchically in how they are deployed on +the Internet. The main 'common' space is `com.simatime`, everything else should +be related to the application. -This isn't totally in place yet, but it's something to work toward. +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. -The main source directory is `lore`. Stuff in `aero` and `apex` should be small -functions specific to the server/client. +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. -The two special locations are `soar` and `bild`. The former is for images and -other assets to be synced to digital ocean's object storage. The latter's -contents are gitignore'd and can be deleted at any time because they will just -be rebuilt later. +Namespaces refer to conceptual boundaries. Implementations can be in any number +of languages, indicated by the file extension. For example, we can have +`com.example.api.hs` and `com.example.api.scm` in order to have an API client in +both Haskell and Scheme. Building `com.example.api` should compile both pieces +of code. -# Development - -To get a development shell, for example to work on ibb, you can do: - - $ nix-shell -A pack.ibb - $ chip/make ibb - -The build system topology is defined in `./default.nix`, so follow the import -paths there to see what's available for building and installing locally. For -example, to build `ibb`: `nix-build -A pack.ibb`. Or, to build the main app -server with all dependencies and configuration: `nix-build -A -depo.nutin-madaj.system`. Omitting `.system` will also build a VM that you can -run locally for testing. - -## Goals of the developer workflow: +# Goals of the developer workflow: - have minimal ceremony - default to asynchrony, but allow for synchronous work when necessary @@ -45,19 +32,16 @@ run locally for testing. 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 resiliance of the production systems. +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 duy, no daily standups. Yes, this policy will affect what code we write, +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. -# Deployment - -To build the production server config locally: +## Org - nix-build -A depo.nutin-madaj.system +## Git -To push the built closure and switch to the new configuration (will ask for ssh -passphrase 2x): +## Email - chip/push nutin-madaj +## IRC |