Merge pull request #127 from rspec/add-contributing-docs

Contributing doc

Author: myronmarston

Rakefile

@@ -4,6 +4,7 @@ require 'pathname'
 require 'bundler'
 require 'time'
 require 'date'
+require 'erb'
 
 Projects = ['rspec', 'rspec-core', 'rspec-expectations', 'rspec-mocks', 'rspec-rails', 'rspec-support']
 UnDocumentedProjects = %w[ rspec rspec-support ]
@@ -287,23 +288,25 @@ end
 namespace :common_markdown_files do
   def update_common_markdown_files_in_repos
     update_files_in_repos('common markdown files', ' [ci skip]') do |name|
-      common_markdown_files_with_comments.each do |file|
+      common_markdown_files_with_comments(name).each do |file|
         full_file_name = ReposPath.join(name, file.file_name)
         full_file_name.write(file.contents)
         full_file_name.chmod(file.mode) # ensure executables are set
       end
     end
   end
 
-  def common_markdown_files_with_comments
+  def common_markdown_files_with_comments(project_name)
     markdown_root = BaseRspecPath.join('common_markdown_files')
     file_names = Pathname.glob(markdown_root.join('**', '{*,.*}')).select do |f|
       f.file?
     end
 
     file_names.map do |file|
       comments_added = false
-      lines = file.each_line.each_with_object([]) do |line, all|
+      content = markdown_file_content(file, project_name)
+
+      lines = content.each_line.each_with_object([]) do |line, all|
         if !comments_added && !line.start_with?('#!')
           all.concat([
             "<!---\n",
@@ -318,13 +321,26 @@ namespace :common_markdown_files do
       end
 
       ReadFile.new(
-        file.relative_path_from(markdown_root),
+        file.relative_path_from(markdown_root).sub(/\.erb$/, ''),
         lines.join,
         file.stat.mode
       )
     end
   end
 
+  ERBRenderer = Struct.new(:project_name, :contents) do
+    def render
+      # Our `binding` makes `project_name` available to the ERB template.
+      ERB.new(contents).result(binding)
+    end
+  end
+
+  def markdown_file_content(file, project_name)
+    raw_contents = file.read
+    return raw_contents unless file.extname == ".erb"
+    ERBRenderer.new(project_name, raw_contents).render
+  end
+
   desc "Update common markdown files"
   task :update_files do
     update_common_markdown_files_in_repos

common_markdown_files/BUILD_DETAIL.md.erb

@@ -0,0 +1,144 @@
+# The CI build, in detail
+
+The [Travis CI build](https://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
+```
+
+It can be useful to run the build steps individually
+to repro a failing part of a Travis build. Let's break
+the build down into the individual steps.
+
+## Specs
+
+RSpec dogfoods itself. Its primary defense against regressions is its spec suite. Run with:
+
+```
+$ bundle exec rspec
+
+# or, if you installed your bundle with `--standalone --binstubs`:
+
+$ bin/rspec
+```
+
+The spec suite performs a couple extra checks that are worth noting:
+
+* *That all the code is warning-free.* Any individual example that produces output
+  to `stderr` will fail. We also have a spec that loads all the `lib` and `spec`
+  files in a newly spawned process to detect load-time warnings and fail if there
+  are any. RSpec must be warning-free so that users who enable Ruby warnings will
+  not get warnings from our code.
+* *That only a minimal set of stdlibs are loaded.* Since Ruby makes loaded libraries
+  available for use in any context, we want to minimize how many bits of the standard
+  library we load and use. Otherwise, RSpec's use of part of the standard library could
+  mask a problem where a gem author forgets to load a part of the standard library they
+  rely on. The spec suite contains a spec that defines a whitelist of allowed loaded
+  stdlibs.
+
+In addition, we use [SimpleCov](https://github.com/colszowka/simplecov)
+to measure and enforce test coverage. If the coverage falls below a
+project-specific threshold, the build will fail.
+
+## Cukes
+
+RSpec uses [cucumber](https://cucumber.io/) for both acceptance testing
+and [documentation](https://relishapp.com/rspec). Since we publish our cukes
+as documentation, please limit new cucumber scenarios to user-facing examples
+that help demonstrate usage. Any tests that exist purely to prevent regressions
+should be written as specs, even if they are written in an acceptance style.
+Duplication between our YARD API docs and the cucumber documentation is fine.
+
+Run with:
+
+```
+$ bundle exec cucumber
+
+# or, if you installed your bundle with `--standalone --binstubs`:
+
+$ bin/cucumber
+```
+
+## YARD documentation
+
+RSpec uses [YARD](http://yardoc.org/) for API documentation on the [rspec.info site](http://rspec.info/).
+Our commitment to [SemVer](htp://semver.org) requires that we explicitly
+declare our public API, and our build uses YARD to ensure that every
+class, module and method has either been labeled `@private` or has at
+least some level of documentation. For new APIs, this forces us to make
+an intentional decision about whether or not it should be part of
+RSpec's public API or not.
+
+To run the YARD documentation coverage check, run:
+
+```
+$ bundle exec yard stats --list-undoc
+
+# or, if you installed your bundle with `--standalone --binstubs`:
+
+$ bin/yard stats --list-undoc
+```
+
+We also want to prevent YARD errors or warnings when actually generating
+the docs. To check for those, run:
+
+```
+$ bundle exec yard doc --no-cache
+
+# or, if you installed your bundle with `--standalone --binstubs`:
+
+$ bin/yard doc --no-cache
+```
+
+## Rubocop
+
+We use [Rubocop](https://github.com/bbatsov/rubocop) to enforce style conventions on the project so
+that the code has stylistic consistency throughout. Run with:
+
+```
+$ bundle exec rubocop lib
+
+# or, if you installed your bundle with `--standalone --binstubs`:
+
+$ bin/rubocop lib
+```
+
+Our Rubocop configuration is a work-in-progress, so if you get a failure
+due to a Rubocop default, feel free to ask about changing the
+configuration. Otherwise, you'll need to address the Rubocop failure,
+or, as a measure of last resort, by wrapping the offending code in
+comments like `# rubocop:disable SomeCheck` and `# rubocop:enable SomeCheck`.
+
+## Run spec files one-by-one
+
+A fast TDD cycle depends upon being able to run a single spec file,
+without the rest of the test suite. While rare, it's fairly easy to
+create a situation where a spec passes when the entire suite runs
+but fails when its individual file is run. To guard against this,
+our CI build runs each spec file individually, using a bit of bash like:
+
+```
+for file in `find spec -iname '*_spec.rb'`; do
+  echo "Running $file"
+  bin/rspec $file -b --format progress
+done
+```
+
+Since this step boots RSpec so many times, it runs much, much
+faster when we can avoid the overhead of bundler. This is a main reason our
+CI build installs the bundle with `--standalone --binstubs` and
+runs RSpec via `bin/rspec` rather than `bundle exec rspec`.
+
+## Running the spec suite for each of the other repos
+
+While each of the RSpec repos is an independent gem (generally designed
+to be usable on its own), there are interdependencies between the gems,
+and the specs for each tend to use features from the other gems. We
+don't want to merge a pull request for one repo that might break the
+build for another repo, so our CI build includes a spec that runs the
+spec suite of each of the _other_ project repos. Note that we only run
+the spec suite, not the full build, of the other projects, as the spec
+suite runs very quickly compared to the full build.
+

common_markdown_files/CONTRIBUTING.md.erb

@@ -0,0 +1,20 @@
+# Contributing
+
+RSpec is a community-driven project that has benefited from improvements from over over *500* contributors.
+We welcome contributions from *everyone*. While contributing, please follow the project [code of conduct](code_of_conduct.md), so that everyone can be included.
+
+If you'd like to help make RSpec better, here are some ways you can contribute:
+
+  - by running RSpec HEAD to help us catch bugs before new releases
+  - by [reporting bugs you encounter](https://github.com/rspec/<%= project_name %>/issues/new)
+  - by [suggesting new features](https://github.com/rspec/<%= project_name %>/issues/new)
+  - by improving RSpec's [Relish](https://relishapp.com/rspec) or [API](http://rspec.info/documentation/) documentation
+  - by improving [RSpec's website](http://rspec.info/) ([source](https://github.com/rspec/rspec.github.io))
+  - by taking part in [feature and issue discussions](https://github.com/rspec/<%= project_name %>/issues)
+  - by adding a failing test for reproducible [reported bugs](https://github.com/rspec/<%= project_name %>/issues)
+  - by reviewing [pull requests](https://github.com/rspec/<%= project_name %>/pulls) and suggesting improvements
+  - by [writing code](DEVELOPMENT.md) (no patch is too small! fix typos or bad whitespace)
+
+If you need help getting started, check out the [DEVELOPMENT](DEVELOPMENT.md) file for steps that will get you up and running.
+
+Thanks for helping us make RSpec better!

common_markdown_files/DEVELOPMENT.md.erb

@@ -0,0 +1,127 @@
+# 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 this project up individually.
+
+## Setting up <%= project_name %> individually
+
+For most contributors, setting up the project individually will be simpler.
+Unless you have a specific reason to use rspec-dev, we recommend using this approach.
+
+Clone the repo:
+
+```
+$ git clone [email protected]:rspec/<%= project_name %>.git
+```
+
+Install the dependencies using [Bundler](http://bundler.io/):
+
+```
+$ cd <%= project_name %>
+$ bundle install
+```
+
+To minimize boot time and to ensure we don't depend upon any extra dependencies
+loaded by Bundler, 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!
+
+## 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.
+
+## Gotcha: Version mismatch from sibling repos
+
+The [Gemfile](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.
+
+## Extra Gems
+
+If you need additional gems for any tasks---such as `benchmark-ips` for benchmarking
+or `byebug` for debugging---you can create a `Gemfile-custom` file containing those
+gem declarations. The `Gemfile` evaluates that file if it exists, and it is git-ignored.
+
+# Running the build
+
+The [Travis CI build](https://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
+```
+
+See [build detail](BUILD_DETAIL.md) for more detail.
+
+# What to Expect
+
+To ensure high, uniform code quality, all code changes (including
+changes from the maintainers!) are subject to a pull request code
+review. We'll often ask for clarification or suggest alternate ways
+to do things. Our code reviews are intended to be a two-way
+conversation.
+
+Here's a short, non-exhaustive checklist of things we typically ask contributors to do before PRs are ready to merge. It can help get your PR merged faster if you do these in advance!
+
+- [ ] New behavior is covered by tests and all tests are passing.
+- [ ] No Ruby warnings are issued by your changes.
+- [ ] Documentation reflects changes and renders as intended.
+- [ ] Rubocop passes (e.g. `bundle exec rubocop lib`).
+- [ ] Commits are squashed into a reasonable number of logical changesets that tell an easy-to-follow story.
+- [ ] No changelog entry is necessary (we'll add it as part of the merge process!)
+
+# Adding Docs
+
+RSpec uses [YARD](http://yardoc.org/) for its API documentation. To
+ensure the docs render well, we recommend running a YARD server and
+viewing your edits in a browser.
+
+To run a YARD server:
+
+```
+$ bundle exec yard server --reload
+
+# or, if you installed your bundle with `--standalone --binstubs`:
+
+$ bin/yard server --reload
+```
+
+Then navigate to `localhost:8808` to view the rendered docs.
+