Initial spec, LICENSE and TODO

1 files changed, 146 insertions, 2 deletions

diff --git a/README.md b/README.md
index 190784e..fd6faf2 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,146 @@
-provisioners
-============
+Trashman: the dystopic package manager
+======================================
+
+    Poorman's Rule:
+            When you pull a plastic garbage bag from its handy dispenser
+            package, you always get hold of the closed end and try to
+            pull it open.
+
+Hello dumpster divers! Wanna know about the new tool in the "ecosystem"?
+
+It pollutes your environment with the modern depressing stack like nodejs and
+docker.
+
+Some stuff are hard to package or upstream makes the effort to keep it harder
+and harder to package. Distros are left behind the planned obsolescence.
+
+This alleviates the pain like ff you find yourself in the urge to install that
+hyped application but have no choice other than run magic commands and install
+untrusted code.
+
+It replace curl-pipe-bash statements like
+
+    curl -L $backdoor_url | bash
+
+by this one:
+
+    trashman install <package>
+
+Instead of being just a shorthand, `trashman` packages try to be as best as possible
+to no fetch keys and scripts from remote locations without some basic checks. So if
+you have to add files into `/etc/apt/trusted.gpg.d`, `trashman` will provide those
+keys or fingerprints instead of donwloading it from somewhere, in which case it could
+be easily tampered.
+
+## Features
+
+* Multi-arch, multi-OS: you might code packages for any distro,
+  be it a GNU/Linux flavour, BSD, Minix or whatever UNIX implementation.
+  Its written in bourne shell language, which guarantees it may run in most
+  systems.
+
+* Multi-language: code your package in the language you want, the way you want.
+  This tool is mainly a script dispatcher. Packages have only to respect some
+  basic conventions like exit statuses.
+
+* Stateless: it doesnt save package state. Instead, packages should provide their
+  own built-in code to detected whether they are installed, half-installed or not.
+
+* Installess: `trashman` itself does not, but can be, installed system-wide.
+  It has no other dependencies other than basic tools like those available
+  in coreutils packages and nowadays common applications like `git`.
+
+* Provides basic automation: instead of always running command by hand, recipes
+  can be included in your deployment scripts.
+
+## Limitations
+
+* It is not a full-feature package manager. Use the one provided by your distro
+  instead. We're not advocating you to stop using your distro way to manage things.
+  We're just providing an alternative way when your distro does not provide easier
+  ways to install some software.
+
+* Do not use your main system for installing `trashman` packages. Use a Virtual Machine
+  instead: this is more manageable and keep the litter isolated from the other parts
+  of your infostructure.
+
+* Not everything can be checked in advance by `trashman` packages. Each package can do
+  it's best to check sources and avoiding running unsigned/untrusted code from remote
+  locations.
+
+* This software is a poor mitigiation and a way to save yourself some time in a growing
+  trend of open source software lifecycles dominated by conglomerates running their
+  "cloud" providing you with "open core" applications, taking over your computing stack.
+
+## Instalation
+
+Simply clone it and add to your `$PATH`:
+
+    git clone https://git.fluxo.info/trashman
+
+You can also verify the latest commit's OpenPGP signature:
+
+    /usr/bin/git -C templater verify-commit HEAD
+
+Note that `/usr/bin/git` is called to avoid any other `git` wrappers or aliases
+you might have available on your shell.
+
+You might also proceed with a system-wide install using `trashman` do install
+itself in your system:
+
+     ./trashman install trashman
+
+## Syncing the codebase
+
+Syncing the codebase is a two-step procedure. First grab upstream changes:
+
+    trashman fetch
+
+This will outpupt current OpenPGP signature's from the last commit. You might
+check that and also check for repository changes. Once you're fine with those,
+do the actual merge:
+
+    trashman merge
+
+## Writing a package
+
+You might use [templater](https://templater.fluxo.info):
+
+    cd path/to/trashman/repo && templater share/package/<package_name> dumpster
+
+packages are simply as having the following files:
+
+* `share/trashman/<name>/info`: describe package purpose.
+* `share/trashman/<name>/<distro>/<action>`: script that runs on a given action.
+
+Where actions can be like `install`, `test`, `remove` or `upgrade`. You don't have
+to implement all actions. Actually, no action is required to create a package, but
+having no action makes it useless.
+
+### Idempotency
+
+Shit. I think I can't even spell this word correctly. Idempowhat? So you're saying
+you want to make your program keep your system in the same state no matter how many
+times you run it?
+
+You don't need a DSL to do that. It's as simply as
+
+    if ! installed $program; then
+      install_program $program
+    fi
+
+It's recommended that you try to make your packaging script to be idempotent.
+
+## Naming candidates
+
+While designing this tools, the following names were considered:
+
+* trashman
+* garbageman
+* dumpster
+* dumpsterize
+* gari
+* lixomanina
+* trashops
+
+This software is dedicated to bands like Trashmen, Trashwomen and Lixomania.