Don’t let the title fool you, the concept here is simple: provide simple scripts in your repositories so – no matter the language or tools used – a newcomer to the code base can get started quickly and easily.
This is an idea I picked up from GitHub – they use it heavily throughout the company and in their open source projects. I have expanded on this a bit and proposed it to my colleagues at VSCO. With some tweaking, we now have the following in almost all our projects my team works on:
script/bootstrapscript/buildscript/testscript/cibuildscript/serverFirst, script/bootstrap installs dependencies and gets your project
ready for development. In a Ruby project, this would be bundle install.
In a Go project, this might be a series of go get calls.
Next, script/build builds your project. This ranges depending upon
the project. For a mobile app, it would be the compile & build step. For a
website, it might be the minification step for your assets. If you’re
running Jekyll, this would be equivalent to jekyll
build.
Then you have script/test. This runs your test suite, whatever it may
be. Notably, this step does not include setting up for tests, unless it’s
required for every single test run. Usually it’s just a call to rspec,
mocha, or what have you.
Naturally, script/cibuild follows. It’s used to setup and execute all
tests. This could be seeding a database, running a linter, whatever. It
should only pass if the code is production-ready.
Last, we have script/server. My team works primarily on server
technology, so this is of crucial importance to us. This allows one to run
the server for development purposes. It’s usually not used in production,
but could easily be incorporated if another server (e.g. nginx or apache)
weren’t being used.
These scripts have saved us a lot of frustration, and a lot of time fighting with package managers, test suites, etc. The best part is that when you clone a repo, you know immediately how to get started, regardless of the language.
I have put these in most of my actively-maintained open source repos that require these steps, projects like Jekyll (and its components), as well as some Golang servers I have built including gossip and ping.
We see the power of common, language-agnostic interfaces all the time. Automating the installation from source of many packages is as simple as wget, tar, ./configure, make, make install. It’s not super easy the first time, but once you learn it, you have access to hundreds of utilities that haven’t been added to your package manager for one reason or another.
Language-agnostic interface scripts like what I describe above are all about making it easier – reducing friction – to develop and iterate on software. Try it out in your projects and see how much time and frustration you can save just by hiding project-level complexity.