Skip to content
This repository was archived by the owner on Nov 30, 2024. It is now read-only.

Commit 957b5ae

Browse files
myronmarstonmyronmarston
committed
Merge pull request #2043 from rspec/update-common-markdown-files-2015-07-27-for-master
Updates from rspec-dev (2015-07-27)
2 parents b1ea8af + bf0c575 commit 957b5ae

File tree

4 files changed

+307
-1
lines changed

4 files changed

+307
-1
lines changed

‎BUILD_DETAIL.md

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
<!---
2+
This file was generated on 2015-07-27T23:49:06-07:00 from the rspec-dev repo.
3+
DO NOT modify it by hand as your changes will get lost the next time it is generated.
4+
-->
5+
6+
# The CI build, in detail
7+
8+
The [Travis CI build](https://travis-ci.org/rspec/rspec-core)
9+
runs many verification steps to prevent regressions and
10+
ensure high-quality code. To run the Travis build locally, run:
11+
12+
```
13+
$ script/run_build
14+
```
15+
16+
It can be useful to run the build steps individually
17+
to repro a failing part of a Travis build. Let's break
18+
the build down into the individual steps.
19+
20+
## Specs
21+
22+
RSpec dogfoods itself. Its primary defense against regressions is its spec suite. Run with:
23+
24+
```
25+
$ bundle exec rspec
26+
27+
# or, if you installed your bundle with `--standalone --binstubs`:
28+
29+
$ bin/rspec
30+
```
31+
32+
The spec suite performs a couple extra checks that are worth noting:
33+
34+
* *That all the code is warning-free.* Any individual example that produces output
35+
to `stderr` will fail. We also have a spec that loads all the `lib` and `spec`
36+
files in a newly spawned process to detect load-time warnings and fail if there
37+
are any. RSpec must be warning-free so that users who enable Ruby warnings will
38+
not get warnings from our code.
39+
* *That only a minimal set of stdlibs are loaded.* Since Ruby makes loaded libraries
40+
available for use in any context, we want to minimize how many bits of the standard
41+
library we load and use. Otherwise, RSpec's use of part of the standard library could
42+
mask a problem where a gem author forgets to load a part of the standard library they
43+
rely on. The spec suite contains a spec that defines a whitelist of allowed loaded
44+
stdlibs.
45+
46+
In addition, we use [SimpleCov](https://github.com/colszowka/simplecov)
47+
to measure and enforce test coverage. If the coverage falls below a
48+
project-specific threshold, the build will fail.
49+
50+
## Cukes
51+
52+
RSpec uses [cucumber](https://cucumber.io/) for both acceptance testing
53+
and [documentation](https://relishapp.com/rspec). Since we publish our cukes
54+
as documentation, please limit new cucumber scenarios to user-facing examples
55+
that help demonstrate usage. Any tests that exist purely to prevent regressions
56+
should be written as specs, even if they are written in an acceptance style.
57+
Duplication between our YARD API docs and the cucumber documentation is fine.
58+
59+
Run with:
60+
61+
```
62+
$ bundle exec cucumber
63+
64+
# or, if you installed your bundle with `--standalone --binstubs`:
65+
66+
$ bin/cucumber
67+
```
68+
69+
## YARD documentation
70+
71+
RSpec uses [YARD](http://yardoc.org/) for API documentation on the [rspec.info site](http://rspec.info/).
72+
Our commitment to [SemVer](htp://semver.org) requires that we explicitly
73+
declare our public API, and our build uses YARD to ensure that every
74+
class, module and method has either been labeled `@private` or has at
75+
least some level of documentation. For new APIs, this forces us to make
76+
an intentional decision about whether or not it should be part of
77+
RSpec's public API or not.
78+
79+
To run the YARD documentation coverage check, run:
80+
81+
```
82+
$ bundle exec yard stats --list-undoc
83+
84+
# or, if you installed your bundle with `--standalone --binstubs`:
85+
86+
$ bin/yard stats --list-undoc
87+
```
88+
89+
We also want to prevent YARD errors or warnings when actually generating
90+
the docs. To check for those, run:
91+
92+
```
93+
$ bundle exec yard doc --no-cache
94+
95+
# or, if you installed your bundle with `--standalone --binstubs`:
96+
97+
$ bin/yard doc --no-cache
98+
```
99+
100+
## Rubocop
101+
102+
We use [Rubocop](https://github.com/bbatsov/rubocop) to enforce style conventions on the project so
103+
that the code has stylistic consistency throughout. Run with:
104+
105+
```
106+
$ bundle exec rubocop lib
107+
108+
# or, if you installed your bundle with `--standalone --binstubs`:
109+
110+
$ bin/rubocop lib
111+
```
112+
113+
Our Rubocop configuration is a work-in-progress, so if you get a failure
114+
due to a Rubocop default, feel free to ask about changing the
115+
configuration. Otherwise, you'll need to address the Rubocop failure,
116+
or, as a measure of last resort, by wrapping the offending code in
117+
comments like `# rubocop:disable SomeCheck` and `# rubocop:enable SomeCheck`.
118+
119+
## Run spec files one-by-one
120+
121+
A fast TDD cycle depends upon being able to run a single spec file,
122+
without the rest of the test suite. While rare, it's fairly easy to
123+
create a situation where a spec passes when the entire suite runs
124+
but fails when its individual file is run. To guard against this,
125+
our CI build runs each spec file individually, using a bit of bash like:
126+
127+
```
128+
for file in `find spec -iname '*_spec.rb'`; do
129+
echo "Running $file"
130+
bin/rspec $file -b --format progress
131+
done
132+
```
133+
134+
Since this step boots RSpec so many times, it runs much, much
135+
faster when we can avoid the overhead of bundler. This is a main reason our
136+
CI build installs the bundle with `--standalone --binstubs` and
137+
runs RSpec via `bin/rspec` rather than `bundle exec rspec`.
138+
139+
## Running the spec suite for each of the other repos
140+
141+
While each of the RSpec repos is an independent gem (generally designed
142+
to be usable on its own), there are interdependencies between the gems,
143+
and the specs for each tend to use features from the other gems. We
144+
don't want to merge a pull request for one repo that might break the
145+
build for another repo, so our CI build includes a spec that runs the
146+
spec suite of each of the _other_ project repos. Note that we only run
147+
the spec suite, not the full build, of the other projects, as the spec
148+
suite runs very quickly compared to the full build.
149+

‎CONTRIBUTING.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<!---
2+
This file was generated on 2015-07-27T23:49:06-07:00 from the rspec-dev repo.
3+
DO NOT modify it by hand as your changes will get lost the next time it is generated.
4+
-->
5+
6+
# Contributing
7+
8+
RSpec is a community-driven project that has benefited from improvements from over over *500* contributors.
9+
We welcome contributions from *everyone*. While contributing, please follow the project [code of conduct](code_of_conduct.md), so that everyone can be included.
10+
11+
If you'd like to help make RSpec better, here are some ways you can contribute:
12+
13+
- by running RSpec HEAD to help us catch bugs before new releases
14+
- by [reporting bugs you encounter](https://github.com/rspec/rspec-core/issues/new)
15+
- by [suggesting new features](https://github.com/rspec/rspec-core/issues/new)
16+
- by improving RSpec's [Relish](https://relishapp.com/rspec) or [API](http://rspec.info/documentation/) documentation
17+
- by improving [RSpec's website](http://rspec.info/) ([source](https://github.com/rspec/rspec.github.io))
18+
- by taking part in [feature and issue discussions](https://github.com/rspec/rspec-core/issues)
19+
- by adding a failing test for reproducible [reported bugs](https://github.com/rspec/rspec-core/issues)
20+
- by reviewing [pull requests](https://github.com/rspec/rspec-core/pulls) and suggesting improvements
21+
- by [writing code](DEVELOPMENT.md) (no patch is too small! fix typos or bad whitespace)
22+
23+
If you need help getting started, check out the [DEVELOPMENT](DEVELOPMENT.md) file for steps that will get you up and running.
24+
25+
Thanks for helping us make RSpec better!

‎DEVELOPMENT.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
<!---
2+
This file was generated on 2015-07-27T23:49:06-07:00 from the rspec-dev repo.
3+
DO NOT modify it by hand as your changes will get lost the next time it is generated.
4+
-->
5+
6+
# Development Setup
7+
8+
Generally speaking, you only need to clone the project and install
9+
the dependencies with [Bundler](http://bundler.io/). You can either
10+
get a full RSpec development environment using
11+
[rspec-dev](https://github.com/rspec/rspec-dev#README) or you can
12+
set this project up individually.
13+
14+
## Setting up rspec-core individually
15+
16+
For most contributors, setting up the project individually will be simpler.
17+
Unless you have a specific reason to use rspec-dev, we recommend using this approach.
18+
19+
Clone the repo:
20+
21+
```
22+
$ git clone [email protected]:rspec/rspec-core.git
23+
```
24+
25+
Install the dependencies using [Bundler](http://bundler.io/):
26+
27+
```
28+
$ cd rspec-core
29+
$ bundle install
30+
```
31+
32+
To minimize boot time and to ensure we don't depend upon any extra dependencies
33+
loaded by Bundler, our CI builds avoid loading Bundler at runtime
34+
by using Bundler's [`--standalone option`](http://myronmars.to/n/dev-blog/2012/03/faster-test-boot-times-with-bundler-standalone).
35+
While not strictly necessary (many/most of our contributors do not do this!),
36+
if you want to exactly reproduce our CI builds you'll want to do the same:
37+
38+
```
39+
$ bundle install --standalone --binstubs
40+
```
41+
42+
The `--binstubs` option creates the `bin/rspec` file that, like `bundle exec rspec`, will load
43+
all the versions specified in `Gemfile.lock` without loading bundler at runtime!
44+
45+
## Using rspec-dev
46+
47+
See the [rspec-dev README](https://github.com/rspec/rspec-dev#README)
48+
for setup instructions.
49+
50+
The rspec-dev project contains many rake tasks for helping manage
51+
an RSpec development environment, making it easy to do things like:
52+
53+
* Change branches across all repos
54+
* Update all repos with the latest code from `master`
55+
* Cut a new release across all repos
56+
* Push out updated build scripts to all repos
57+
58+
These sorts of tasks are essential for the RSpec maintainers but will
59+
probably be unnecessary complexity if you're just contributing to one
60+
repository. If you are getting setup to make your first contribution,
61+
we recommend you take the simpler route of setting up rspec-core
62+
individually.
63+
64+
## Gotcha: Version mismatch from sibling repos
65+
66+
The [Gemfile](Gemfile) is designed to be flexible and support using
67+
the other RSpec repositories either from a local sibling directory
68+
(e.g. `../rspec-<subproject>`) or, if there is no such directory,
69+
directly from git. This generally does the "right thing", but can
70+
be a gotcha in some situations. For example, if you are setting up
71+
`rspec-core`, and you happen to have an old clone of `rspec-expectations`
72+
in a sibling directory, it'll be used even though it might be months or
73+
years out of date, which can cause confusing failures.
74+
75+
To avoid this problem, you can either `export USE_GIT_REPOS=1` to force
76+
the use of `:git` dependencies instead of local dependencies, or update
77+
the code in the sibling directory. rspec-dev contains rake tasks to
78+
help you keep all repos in sync.
79+
80+
## Extra Gems
81+
82+
If you need additional gems for any tasks---such as `benchmark-ips` for benchmarking
83+
or `byebug` for debugging---you can create a `Gemfile-custom` file containing those
84+
gem declarations. The `Gemfile` evaluates that file if it exists, and it is git-ignored.
85+
86+
# Running the build
87+
88+
The [Travis CI build](https://travis-ci.org/rspec/rspec-core)
89+
runs many verification steps to prevent regressions and
90+
ensure high-quality code. To run the Travis build locally, run:
91+
92+
```
93+
$ script/run_build
94+
```
95+
96+
See [build detail](BUILD_DETAIL.md) for more detail.
97+
98+
# What to Expect
99+
100+
To ensure high, uniform code quality, all code changes (including
101+
changes from the maintainers!) are subject to a pull request code
102+
review. We'll often ask for clarification or suggest alternate ways
103+
to do things. Our code reviews are intended to be a two-way
104+
conversation.
105+
106+
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!
107+
108+
- [ ] New behavior is covered by tests and all tests are passing.
109+
- [ ] No Ruby warnings are issued by your changes.
110+
- [ ] Documentation reflects changes and renders as intended.
111+
- [ ] Rubocop passes (e.g. `bundle exec rubocop lib`).
112+
- [ ] Commits are squashed into a reasonable number of logical changesets that tell an easy-to-follow story.
113+
- [ ] No changelog entry is necessary (we'll add it as part of the merge process!)
114+
115+
# Adding Docs
116+
117+
RSpec uses [YARD](http://yardoc.org/) for its API documentation. To
118+
ensure the docs render well, we recommend running a YARD server and
119+
viewing your edits in a browser.
120+
121+
To run a YARD server:
122+
123+
```
124+
$ bundle exec yard server --reload
125+
126+
# or, if you installed your bundle with `--standalone --binstubs`:
127+
128+
$ bin/yard server --reload
129+
```
130+
131+
Then navigate to `localhost:8808` to view the rendered docs.
132+

‎code_of_conduct.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
This file was generated on 2015-07-09T22:24:42-07:00 from the rspec-dev repo.
2+
This file was generated on 2015-07-27T23:49:06-07:00 from the rspec-dev repo.
33
DO NOT modify it by hand as your changes will get lost the next time it is generated.
44
-->
55

0 commit comments

Comments
 (0)