Every project should have a
README.md file in their Git repository. It should contain everything anyone ever needs to get started working on the project.
- External links (Trello, JIRA, Slack, and so on)
- Required software and how to install them
- Setting up a development environment
- Deployment instructions
- Running tests
When a new developer joins the team, they should be able to get by by simply telling them to "read the readme file". This helps the project in many ways:
- Makes it easy for people to join the team.
- Helps out team members when moving to new laptops.
Be sure to maintain the Readme file. Things may change and get added to the project that the Readme may need to be updated. Don't let it stagnate, you'll never know when you'll need it!
This is a bare example that manages to cram everything in the list above in just a few sections.
- Ruby 2.3
- Redis 2.3
- PostgreSQL 9.5
- Bundler (
gem install bundler)
For OSX, we recommend you install via:
- Ruby via RVM
- Redis via Homebrew (
brew install redis)
- Postgres via Homebrew (
brew install postgres)
Install dependencies via Bundler and npm:
git checkout https://github.com/x/my_project.git cd my_project bundle npm install
Run a Rails development server:
bundle exec rails s
Tests are managed via RSpec.
bundle exec rspec
Deployments are managed via SemaphoreCI using Capistrano.
developis automatically deployed to staging.oursite.com, while
masteris auto-deployed to oursite.com production. To manually invoke a deployment, use:
bundle exec cap staging deploy # staging.oursite.com bundle exec cap production deploy # oursite.com
Note: this section mostly applies to private projects. Different ettiquette applies to Readme files in open source projects.
Next: Help teammates understand your work with documentation.