Encourage users to customize the permitted word list in RSpec/ContextWording (was: Add before and after to default list)

[elebow]

Add before and after to the RSpec/ContextWording default list. This allows for more expressive context descriptions.

Example:

# bad
context 'record not yet saved'

# good
context 'when the record is not yet saved'

# even better
context 'before the record is saved'

Also add items that are mentioned in the documentation but not included in the default config: if, unless, for.

on-behalf-of: @Cofense oss@cofense.com

---

Before submitting the PR make sure the following are checked:

• Feature branch is up-to-date with master (if not - rebase it).
• Squashed related commits together.
• Added tests.
• Added an entry to the changelog if the new code introduces user-observable changes.
• The build (bundle exec rake) passes (be sure to run this locally, since it may produce updated documentation that you will need to commit).

If you have created a new cop:

• Added the new cop to config/default.yml.
• The cop documents examples of good and bad code.
• The tests assert both that bad code is reported and that good code is not reported.

[pirj]

Can you please provide a full example group for which 'before the record is saved' is a good title?

Just for the reference, similar request: #757

We're trying to stick to https://rspec.rubystyle.guide/#context-descriptions (https://github.com/rubocop-hq/rspec-style-guide#context-descriptions) for defaults.
You are welcome to contribute to those guidelines as well.

[elebow]

Thanks for the pointers to other PRs. I've opened rubocop/rspec-style-guide#108 which seems like a better place for the discussion.

---

An example where the suggested change improves readability.

Suppose an application has a user creation flow with several stages:

1. A user creates an account
2. The app sends an email for the user to confirm their address
3. After email is confirmed, an admin must manually approve the new user

A high-level behavioral spec may want to examine the situation at intermediate points in the process.

describe 'User creation' do
  context 'when the user has not yet confirmed their email address' do
  end

  context 'when the user has confirmed their email address' do
    # alternatively, 'when an admin has not yet approved the user'
  end

  context 'when an admin has approved the user' do
  end
end

This is adequate, but it does not do a good job communicating the flow of time—The groups are not alternative states, but a sequence of states. Words like before and after let the descriptions convey that more naturally:

describe 'User creation' do
  context 'before the user confirms their email address' do
  end

  context 'after the user has confirmed their email address' do
    # alternatively, 'before an admin approves the user'
  end

  context 'after an admin has approved the user' do
  end
end

[pirj]

Basing on the discussion in #757, and keeping in mind that:

• the style guide is permissive enough with its "this typically means"
• we mention "a small list of preferred words" in the cop docs
• "RuboCop encourages users to configure it to match the project style" (but it's not explicitly mentioned in RuboCop RSpec's README!)
• "Ask a hundred developers how to test an application, and you’ll get a hundred different answers."

do you think there's a way to suggest the users relax this cop in a way that lets them move forward with their style of choice without making it completely useless by default because it's too permissive?

[elebow]

In light of rubocop/rspec-style-guide#108, a documentation-only change to the ContextWording cop seems in order. Changes pushed to this PR.

Context descriptions are written in freeform human language, so it is impossible to foresee all acceptable cases. This change adds text to the documentation encouraging users to configure the list of permitted prefixes to meet their needs.

This change may also resolve #510.

[pirj]

Looks good, thank you!

[pirj]

If you're up for making another correction, the namespace has changed from reachlocal to rubocop-hq.

[elebow]

If it's the same content as https://rspec.rubystyle.guide, maybe it's better to have only one?

[pirj]

Fair enough.

[elebow]

I removed the github.com link, since the rubystyle.guide link has the same content in a better form. Changes pushed.