Make README more accessible to novices #2042

rlue · 2018-11-19T09:39:18Z

This is an extensive rewrite of the README written as a follow-up to issue #1840. It has the following goals:

give explanatory context for users who are new to both RSpec and RSpec rails,
name section headings with the questions they answer,
make each section concise enough that a reader can comprehend the visual structure of the document on a quick scroll-through,
replace "redundant" info (code blocks that demonstrate concepts readily available in the cucumber doc scenarios, or upgrade notes) with links to corresponding cucumber docs,
update for latest version of RSpec Rails (specifically re: recommendations for controller specs and feature specs).

Notably, I've removed the section on rake tasks, and mostly removed the section on FactoryBot/Capybara. I've also added a link to betterspecs.org as an RSpec style guide.

Thoughts?

JonRowe

Wow this is a mega PR. I'm sure I will have more feedback later on but this should be a good start.

I really like the refactoring of the first bits, but then it gets a bit more wobbly, if you have any questions about the feedback happy to discuss.

features/view_specs/view_spec.feature

README.md

JonRowe · 2018-11-19T16:42:22Z

README.md

+Assuming you haven’t [modified the default `rails_helper.rb` configuration][],
+simply place the spec in the appropriate folder
+(_e.g.,_ `spec/models/` for model specs)
+and RSpec will set its type automatically.


Don't mention this, we don't want to encourage it.

I'd still like this changed to describe assigning a type by hand, and not mentioning setting type automatically.

This still needs inverting. The default should be writing types, that it can happen automatically is likely going to be removed in a later RSpec version, so it should not be mentioned.

Sorry @JonRowe, just noticed this now. Does the current version work for you?

JonRowe · 2018-11-19T16:43:50Z

README.md

-#### Upgrade note
+RSpec Rails provides three types of specs
+for integration testing the application as a whole—in other words,
+specifying what the client sees when interacting with it.


Not technically true, only feature / system specs have any javascript capability so they're the only ones capable of being end to end. Also integration tests don't have to be end to end, see earlier notes about confusing terminology.

Understood.

How do you feel about the following distinction instead?

RSpec Rails provides three types of specs that do not directly correspond to any Rails application component.

I think this was the source of my original confusion about what certain spec types were for, and is (for me) the main criterion that distinguishes which spec types are worth explaining in detail and which should simply be linked to the Cucumber docs.

How about

RSpec Rails also provides some end to end (entire application) testing capability, to specify the interaction with the client.

My understanding was that you didn't want request specs grouped under the end-to-end umbrella. Would you like me to extract the Request Specs subsection into its own, separate section, or are you okay with leaving them there?

README.md

fables-tales · 2018-11-19T21:14:20Z

I like parts of what I've read so far to be sure. I'd like to see Jon's feedback addressed then will give it a once over.

rlue · 2018-11-20T04:38:12Z

Thanks for your super fast feedback, guys. Learning a lot here.

README.md

benoittgt

LGTM. I added one comment but this is not a blocker for me. Thanks a lot for the work. Waiting for @JonRowe or @samphippen for the final review :)

CI need to be fixed first "README.md has spaces on the EOL on lines 30, 233, 356"

benoittgt

Could you please check for CI issue?
README.md has spaces on the EOL on lines 30, 233, 356

benoittgt

LGTM thanks

JonRowe

Sorry for the delay, its a long PR to review, looking closer! @samphippen you want to jump in with anything?

README.md

JonRowe · 2018-12-12T14:48:57Z

README.md


-## Installation
+In RSpec, tests are not just scripts that verify your application code;
+they’re also detailed explanations of how the application is supposed to behave,


Can we have they are apparently expanding contractions is better for non native speaker understandability.

I use contractions a lot throughout the rest of the document (you're / you'll / you've / there's / it's / I'm / what's), and feel strongly that they contribute to a less stuffy, more approachable tone.

On the other hand, I can appreciate the principle, and if you feel strongly about it, then I can find another way to say it.

@xaviershay would you mind pitching in here? I believe I learnt the "don't use contractions" rule from your good self.

README.md

JonRowe · 2018-12-12T14:55:16Z

README.md

+Assuming you haven’t [modified the default `rails_helper.rb` configuration][],
+simply place the spec in the appropriate folder
+(_e.g.,_ `spec/models/` for model specs)
+and RSpec will set its type automatically.


I'd still like this changed to describe assigning a type by hand, and not mentioning setting type automatically.

README.md

benoittgt · 2018-12-13T05:58:55Z

Thanks for the last changes. It's much better with them.

README.md

fables-tales · 2018-12-20T12:46:01Z

README.md

-```ruby
-render
-expect(rendered).to match /Some text expected to appear on the page/
+RSpec.describe User, type: :model do


could we bring this example up to above where the table of types is?

fables-tales · 2018-12-20T12:47:09Z

@rlue I had a small question (for @JonRowe) and one requested change. Do let me know once you can get to them.

rlue · 2019-01-04T04:12:01Z

Hey happy new year guys! Sorry for the delay; I've been out of the country for the past two weeks.

@samphippen, what do you think of this round of changes?

fables-tales · 2019-01-07T15:09:46Z

This looks really good!

fables-tales · 2019-01-07T15:10:53Z

@rlue if you rebase this against master, you should have your build fixed because of the bundler issue.

README.md

rlue · 2019-01-07T22:16:06Z

@samphippen, my understanding is that rebasing rewrites history, which would make it impossible to push to the same remote branch, so I just merged instead—is that okay?

@JonRowe, I believe the only remaining open critique you had was about the contraction (they're) on line 7. Let me know if I'm missing anything else, or if that's a dealbreaker for you.

rlue · 2019-01-08T22:30:21Z

Thanks for everything, guys. The Travis CI build is still failing, and I'm puzzling over why.

The build that's failing is for 42bcf1b, a merge commit of fe43309 (master, passing CI) and 368e747 (from my fork, failing CI). A diff of 42bcf1b / fe43309 shows that the only changed files are README.md and a couple of cucumber features. The CI failures are all related to Bundler.

Some look like this:

$ rvm use 2.2.10 --install --binary --fuzzy
...
ruby-2.2.10 - #importing gemset /home/travis/.rvm/gemsets/global.gems..................................there was an error installing gem bundler
...
$ gem install bundler
ERROR:  Error installing bundler:
	The last version of bundler (>= 0) to support your Ruby & RubyGems was 1.17.3. Try installing it with `gem install bundler -v 1.17.3`
	bundler requires Ruby version >= 2.3.0. The current ruby version is 2.2.0.
The command "gem install bundler" failed and exited with 1 during .

Others look like this:

$ bundle install --binstubs --path ../bundle --retry=3 --jobs=3
The dependency jruby-openssl (>= 0) will be unused by any of the platforms Bundler is installing for. Bundler is installing for ruby but the dependency is only for java. To add those platforms to the bundle, run `bundle lock --add-platform java`.
Fetching gem metadata from https://rubygems.org/........
Fetching gem metadata from https://rubygems.org/.
Resolving dependencies...
Bundler could not find compatible versions for gem "bundler":
  In Gemfile:
    rails (~> 4.2.0) was resolved to 4.2.11, which depends on
      bundler (>= 1.3.0, < 2.0)
  Current Bundler version:
    bundler (2.0.1)
This Gemfile requires a different version of Bundler.
Perhaps you need to update Bundler by running `gem install bundler`?
Could not find gem 'bundler (>= 1.3.0, < 2.0)', which is required by gem 'rails
(~> 4.2.0)', in any of the sources.
Bundler could not find compatible versions for gem "cucumber":
  In Gemfile:
    cucumber (~> 1.3.5)
    aruba (~> 0.5.4) was resolved to 0.5.4, which depends on
      cucumber (>= 1.1.1)
Bundler could not find compatible versions for gem "nokogiri":
  In Gemfile:
    nokogiri (= 1.8.5)
    capybara (~> 2.2.0) was resolved to 2.2.1, which depends on
      nokogiri (>= 1.3.3)
The command "eval bundle install --binstubs --path ../bundle --retry=3 --jobs=3 " failed. Retrying, 2 of 3.

I haven't looked at every single failing test case (there are a lot), but all the ones I've seen look like one of the two above.

Any ideas?

JonRowe · 2019-01-08T22:31:19Z

Build is broken pending #2061

JonRowe · 2019-01-09T09:34:52Z

#2061 is merged so a rebase/merge would get this green hopefully.

rlue · 2019-01-09T22:45:15Z

All ready!

fables-tales · 2019-01-10T14:12:28Z

Thank you for all your work here @rlue

rlue · 2019-01-10T23:04:59Z

Same to all three of you (especially @JonRowe)!

@JonRowe

* Make README more accessible to novices * Amend per @JonRowe's review * Apply second round of fixes per @JonRowe's review * Amend per @benoittgt's code review * Remove trailing whitespace * Apply more fixes per @JonRowe's review * Change semicolon to full colon in intro * Fix punctuation in intro * Apply changes per @samphippen's review * Fix description of spec type assignment, per @JonRowe's suggestion * Rephrase introduction per @mikegee's review

@JonRowe

* Make README more accessible to novices * Amend per @JonRowe's review * Apply second round of fixes per @JonRowe's review * Amend per @benoittgt's code review * Remove trailing whitespace * Apply more fixes per @JonRowe's review * Change semicolon to full colon in intro * Fix punctuation in intro * Apply changes per @samphippen's review * Fix description of spec type assignment, per @JonRowe's suggestion * Rephrase introduction per @mikegee's review

Make README more accessible to novices

b690f70

JonRowe requested changes Nov 19, 2018

View reviewed changes

Amend per @JonRowe's review

0449b2f

Apply second round of fixes per @JonRowe's review

2bf4a6f

benoittgt reviewed Nov 28, 2018

View reviewed changes

README.md Show resolved Hide resolved

README.md Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

Amend per @benoittgt's code review

18ee154

benoittgt reviewed Dec 7, 2018

View reviewed changes

README.md Show resolved Hide resolved

benoittgt previously approved these changes Dec 7, 2018

View reviewed changes

benoittgt requested changes Dec 7, 2018

View reviewed changes

Remove trailing whitespace

db1fdf7

benoittgt approved these changes Dec 12, 2018

View reviewed changes

JonRowe requested changes Dec 12, 2018

View reviewed changes

Apply more fixes per @JonRowe's review

3bf7098

rlue added 2 commits December 13, 2018 19:36

Change semicolon to full colon in intro

2fd2e90

Fix punctuation in intro

bba982b

fables-tales requested changes Dec 20, 2018

View reviewed changes

Apply changes per @samphippen's review

758801c

Fix description of spec type assignment, per @JonRowe's suggestion

a736988

fables-tales approved these changes Jan 7, 2019

View reviewed changes

mikegee reviewed Jan 7, 2019

View reviewed changes

README.md Outdated Show resolved Hide resolved

rlue added 2 commits January 8, 2019 06:10

Rephrase introduction per @mikegee's review

76220cf

Merge remote-tracking branch 'upstream/master' into doc/readme

368e747

JonRowe approved these changes Jan 8, 2019

View reviewed changes

Merge remote-tracking branch 'upstream/master' into doc/readme

986578d

fables-tales merged commit e75c725 into rspec:master Jan 10, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make README more accessible to novices #2042

Make README more accessible to novices #2042

rlue commented Nov 19, 2018 •

edited

Loading

JonRowe left a comment

JonRowe Nov 19, 2018

rlue Nov 20, 2018

JonRowe Dec 12, 2018

JonRowe Dec 20, 2018

rlue Jan 5, 2019

JonRowe Nov 19, 2018

rlue Nov 20, 2018

JonRowe Nov 20, 2018

rlue Nov 21, 2018

fables-tales commented Nov 19, 2018

rlue commented Nov 20, 2018

benoittgt left a comment

benoittgt left a comment

benoittgt left a comment

JonRowe left a comment

JonRowe Dec 12, 2018

rlue Dec 13, 2018

JonRowe Dec 14, 2018

JonRowe Dec 12, 2018

benoittgt commented Dec 13, 2018

fables-tales Dec 20, 2018

rlue Jan 5, 2019

fables-tales commented Dec 20, 2018

rlue commented Jan 4, 2019

fables-tales commented Jan 7, 2019

fables-tales commented Jan 7, 2019

rlue commented Jan 7, 2019

rlue commented Jan 8, 2019

JonRowe commented Jan 8, 2019

JonRowe commented Jan 9, 2019

rlue commented Jan 9, 2019

fables-tales commented Jan 10, 2019

rlue commented Jan 10, 2019

Make README more accessible to novices #2042

Make README more accessible to novices #2042

Conversation

rlue commented Nov 19, 2018 • edited Loading

JonRowe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fables-tales commented Nov 19, 2018

rlue commented Nov 20, 2018

benoittgt left a comment

Choose a reason for hiding this comment

benoittgt left a comment

Choose a reason for hiding this comment

benoittgt left a comment

Choose a reason for hiding this comment

JonRowe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

benoittgt commented Dec 13, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fables-tales commented Dec 20, 2018

rlue commented Jan 4, 2019

fables-tales commented Jan 7, 2019

fables-tales commented Jan 7, 2019

rlue commented Jan 7, 2019

rlue commented Jan 8, 2019

JonRowe commented Jan 8, 2019

JonRowe commented Jan 9, 2019

rlue commented Jan 9, 2019

fables-tales commented Jan 10, 2019

rlue commented Jan 10, 2019

rlue commented Nov 19, 2018 •

edited

Loading