The concept of failure is central to the design process, and it is by thinking in terms of obviating failure that successful designs are achieved. It has long been practically a truism among practicing engineers and designers that we learn much more from failures than from successes.

— Henry Petroski
Design Paradigms: Case Histories of Error and Judgment in Engineering

boot-fails

This is a simple task library and app designed to make it easy to break things in boot and learn from the experience.

You can read all the documentation you want, but the way to really learn boot is to use it. However, there is a lot of functionality in boot. If you’re in the middle of writing a boot library of any complexity, you might find you need to do some experimenting with some part of the boot API in order to really understand how to use it properly. If you do that in your dev tree its easy to clutter up your code, and even lose track of which bits of code are for ad-hoc experimenting and which are actually needed.

This project provides a minimal framework that can be used to explore boot without cluttering up a real project. Out of the box all it does is provide a structure and some debugging tasks you can use to dump information about boot’s state. Clojure beginners can learn from the source code how to examine namespaces, list interned symbols, etc.

Of course you can also use the excellent boot-new or similar to create a new boot project and start playing around there. boot-fails is not really intended as a template, though. It includes (or will include, maybe) stuff that is useful for exploring and breaking things that you would not want in a template. You would want to use boot-new once you’ve played around with boot-fails, rather than use the latter as the starting point of a new project.

getting started

Fork/clone the project, then install the library component and run the app component:

git clone https://github.com/mobileink/boot-fails.git
cd boot-fails/lib
boot watch pom jar install

The lib project is tmp.boot/boot-fails, which installs to ~/.m2/repository/tmp/ so it doesn’t clutter your repo.

The boot watch pom jar install pipeline is what allows you to experiment with the library. The watch task will monitor the sources, and when it detects changes it will launch the remainder of the pipeline, which will install the updated version into the local repo.

Then start experimenting with the app, which uses the lib:

$ cd ../app
$ cat build.boot
$ boot -vb        ## standard boot cmd to dump boot config to stdout
$ boot help       ## look for the fails tasks
$ boot fails/nss -h  ## print help for task fails/nss
$ boot fails/nss  ## list namespaces
$ boot fails/ns- -n foo.bar  ## list syms interned in ns foo.bar

out-of-the-box failure

I put this thing together as a result of not really understanding some things about namespaces and using vars to store configuration info. Best practices say don’t put config info in the environment, and don’t use a "global" (i.e. boot.user) var either. I wanted an example of how violating those guidelines might lead to heartache. This code doesn’t actually demo such problems, it just exhibits detailed info about some vars so you can see what’s up with them. Look for the three *-config vars in the lib and app, and the vars task in the lib.

In the near future I expect to foul up some configuration-related code and update this with some more genuine fails.

breaking stuff

If you want to start breaking things, you should make a git branch for each "topic" you explore. That keeps the master branch clean so you can pull any updates to it easily.

The envisioned usage is that you would spend a little time exploring some bits of the API in a dedicated branch, and then delete it once you’ve learned what not to do.

contributing fails

If you have a nice fail that you think others could learn from, put it on a branch and I’ll add it. Just make sure it contains only the code essential to illustrating the fail, to keep things clean and simple.

roadmap

• add some tasks designed to explore pods and show how to misuse them.

Some fails to be added:

• sh instead of dosh: boot-clj/boot#177