I’m pretty sure that everyone has at some point experienced this mixed feeling of disbelieve and confusion when looking at code that was written weeks/months or years ago realizing that you have no idea what the code was meant to do.
We develop and apply a lot of patterns and technics to prevent this situations from happing but keep on forgetting that someone somewhere somtime has to turn our sourcecode into a working application and deploy it somewhere, or even better: continue developing it.
This is typically the point where you realize that there is a lot of knowledge about how to build and deploy your code that is only available in the peoples heads or one someones machine who by accident has the right set of versions and tools to get everything running.
This post will describe by example some patterns on how to keep this knowledge in your repository next to your code and how to ensure that it works in (almost) every envrionment.
OSS/closed source does not matter
to transform our sourcecode into something useful No one uses gcc/javac/… directly anymore so why should someone interested in our software be hassled with working with …
The example project wich I will use to demomstrate the key points of a run file is the simple and well known TodoMVC application. The backend is implemented in Java and the frontend is made with Vue.js. For easier distribution we will produce a Docker image of our application and provide Terraform based code that deploys our application to AWS.
Choice of scripting language
If there is a better tool use it
Even though it’s hard, try not to get carried away when writing your runfile. Before adding a new task ask yourself: Is there already something that does the job I want? If so, then use it.
There are obvious examples like when you try to compile some Java code don’t call
javac by hand, use Gradle or if you must Maven. The same goes for C++ that nowadays noone in his (TODO) right state of mind would compile by hand but use an appropiate build tool like CMake for example.
Prepare the enviroment
Check tools and versions
deploy secrets from pass/gopass/…?
helps new developers
should be executable
no prerequsites to run the file
not to big, use subcommands if possible to strucutre your file
ensure environment as much as possible
if not possible to set up environment at least check it
everything in current dir is ok
lint all the things
provide meaningful help (not in readme, but in code
use a common scripting language (platforms)
allow to override possibly enviroment dependent stuff
use it in ci
dont misue run, use gralde, rake or whatever if suitable
run is only a starter