2 minutes estimated reading time.

Writing a good bin/setup

Matt Bettinson — 09/06/2018

Nothing is better than cloning a code repository, running the bin/setup, and everything about the project just works. It’s the developer equivalent of waking up before your alarm goes off and realizing you can sleep for another two hours.

A good bin/setup can mean the difference between a frustrating on-boarding process and a fantastic one.

When you have a completed bin/setup, you have an easy way to get new and existing developers up and running quickly, stress-free. It can also streamline continuous integration setup and maintenance. A good bin/setup gives you peace of mind when setting up a new machine and offloads the mental work of project setup to a verifiable tool.

What makes a good bin/setup?

A good bin/setup is quick, efficient, and reproducible. It is comprised of everything you need to get up and running with a project. It can reduce the mental friction a README can present and lead to a more pleasant starting point when cloning the codebase. A setup script can include:

Installation of dependencies (i.e. bundle install, composer install, npm install)
Setting up a database (i.e. rails db:create)
Providing necessary information when a step fails or needs to hand off responsibility

A good bin/setup should be in the language that the project is written in. If this isn’t possible, a Bash script is the next best choice.

Here are some examples of good bin setups: setup.sh · GitHub and pachonk/celebrity-picture-rater · GitHub. These are well documented, simple, and written in a language appropriate for the project. They gracefully fail and provide users with the necessary information when they do.

If your project is fleshed out but doesn’t yet have a solid bin/setup, it may be a good idea to clone the project on a fresh machine and get it building from scratch while taking notes during the process. You should then automate any manual steps you can to get the project running, and documenting more involved steps that would take too much effort to automate. A good bin/setup is worth its weight in gold. I wish you luck on your journey of project setup enlightenment.