Over my years developing Ruby and Rails applications I have not seen a proper walkthrough of how Rails fits together from a base site perspective. Most of these concepts will not be new to most Rails engineers; however it’s always good for a refresher.
Let’s start with README.md
This file should give a brief explanation of what your application is/does. It should include things like how to setup in Dev, Staging and Production. It should include a list of application dependencies as well as how to install them on all the target systems. When writing this file, assume that the person reading has never used a Ruby application before especially not the one this file is in.
The installation should be in-depth. You want to ensure that every new engineer installs their application the same way as everyone else. That does not necessarily mean that other engineers will break out of the box and choose their own path, but it’s good to give a direction to all new engineers. A sample Installation blurb might look like.
ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"brew install gitbrew install rbenvbrew install ruby-buildsudo apt-get updatesudo apt-get upgradesudo apt-get install nodejs libc6-dev bison openssl libreadline6 libreadline6-dev zlib1g zlib1g-dev libssl-dev libyaml-dev libxml2-dev autoconfgit clone https://github.com/sstephenson/rbenv.git ~/.rbenvecho 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrcecho 'eval "$(rbenv init -)"' >> ~/.bashrcgit clone https://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-buildetc… You want to give the most detailed instructions possible. Because you never know what level of expertise your new engineer is. Also it makes it easier to reinstall if you need to. It’s a lot faster to get started if you already know everything you need to do. Don’t forget to include things like installing your database software (i.e. MySQL) and creating, migrating, and loading your database dump.
If your application does image processing it’s very likely you might need a dependency like ImageMagick. If you include this dependency in your README.md it will lessen the amount of work, questions and hassle when debugging application issues later. An example of how this might look might be.
We know the application is ruby, but always specify the intended version in the README.md!
Don’t forget to include deploy instructions to Staging, QA, Production, etc… If your deploys are automatic by CI don’t forget to note that here as well.
If you are using continuous integration, see if a CI build status badge is available for the primary branch. If so place it at the top of the readme along with CI access instructions.