WIP: start on DEVELOPMENT.md

Author: myronmarston

common_markdown_files/DEVELOPMENT.md.erb

@@ -0,0 +1,91 @@
+# Development Setup
+
+Generally speaking, you only need to clone the project and install
+the dependencies with [Bundler](http://bundler.io/). You can either
+get a full RSpec development environment using
+[rspec-dev](https://github.com/rspec/rspec-dev#README) or you can
+set up this project individually.
+
+## Using rspec-dev
+
+See the [rspec-dev README](https://github.com/rspec/rspec-dev#README)
+for setup instructions.
+
+The rspec-dev project contains many rake tasks for helping manage
+an RSpec development environment, making it easy to do things like:
+
+* Change branches across all repos
+* Update all repos with the latest code from `master`
+* Cut a new release across all repos
+* Push out updated build scripts to all repos
+
+These sorts of tasks are essential for the RSpec maintainers but will
+probably be unnecessary complexity if you're just contributing to one
+repository. If you are getting setup to make your first contribution,
+we recommend you take the simpler route of setting up <%= project_name %>
+individually.
+
+## Setting up <%= project_name %> individually
+
+Clone the repo:
+
+```
+$ git clone [email protected]:rspec/<%= project_name %>.git
+```
+
+Install the dependencies using [Bundler](http://bundler.io/):
+
+```
+$ cd <%= project_name %>
+$ bundle install
+```
+
+For reasons discussed below, our CI builds avoid loading Bundler at runtime
+by using Bundler's [`--standalone option`](http://myronmars.to/n/dev-blog/2012/03/faster-test-boot-times-with-bundler-standalone).
+While not strictly necessary (many/most of our contributors do not do this!),
+if you want to exactly reproduce our CI builds you'll want to do the same:
+
+```
+$ bundle install --standalone --binstubs
+```
+
+The `--binstubs` option creates the `bin/rspec` file that, like `bundle exec rspec`, will load
+all the versions specified in `Gemfile.lock` without loading bundler at runtime!
+
+## Gotcha: Version mismatch from sibling repos
+
+The [../Gemfile] is designed to be flexible and support using
+the other RSpec repositories either from a local sibling directory
+(e.g. `../rspec-<subproject>`) or, if there is no such directory,
+directly from git. This generally does the "right thing", but can
+be a gotcha in some situations. For example, if you are setting up
+`rspec-core`, and you happen to have an old clone of `rspec-expectations`
+in a sibling directory, it'll be used even though it might be months or
+years out of date, which can cause confusing failures.
+
+To avoid this problem, you can either `export USE_GIT_REPOS=1` to force
+the use of `:git` dependencies instead of local dependencies, or update
+the code in the sibling directory. rspec-dev contains rake tasks to
+help you keep all repos in sync.
+
+# Running the build
+
+The [Travis CI build](travis-ci.org/rspec/<%= project_name %>)
+runs many verification steps to prevent regressions and
+ensure high-quality code. To run the Travis build locally, run:
+
+```
+$ script/run_build
+```
+
+Let's break this down into the individual steps that are part of the build.
+
+## Running the spec suite
+
+```
+$ bundle exec rspec
+
+# or, if you installed your bundle with `--standalone --binstubs`:
+
+$ bin/rspec
+```