Updated common plaintext files (from rspec-dev)main

JonRowe · JonRowe · commit a4d858ef0cc7 · 2020-12-25T18:48:30.000Z
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -1,4 +1,4 @@
-# This file was generated on 2020-12-23T21:24:00+01:00 from the rspec-dev repo.
+# This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
 # DO NOT modify it by hand as your changes will get lost the next time it is generated.
 
 github: [JonRowe, benoittgt]
diff --git a/BUILD_DETAIL.md b/BUILD_DETAIL.md
@@ -1,5 +1,5 @@
 <!---
-This file was generated on 2019-12-05T21:32:23+00:00 from the rspec-dev repo.
+This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
 DO NOT modify it by hand as your changes will get lost the next time it is generated.
 -->
 
@@ -97,22 +97,23 @@ $ bundle exec yard doc --no-cache
 $ bin/yard doc --no-cache
 ```
 
-## Rubocop
+## RuboCop
 
-We use [Rubocop](https://github.com/rubocop-hq/rubocop) to enforce style conventions on the project so
-that the code has stylistic consistency throughout. Run with:
+We use [RuboCop](https://github.com/rubocop-hq/rubocop) to enforce style
+conventions on the project so that the code has stylistic consistency
+throughout. Run with:
 
 ```
-$ bundle exec rubocop
+$ bundle exec rubocop lib
 
 # or, if you installed your bundle with `--standalone --binstubs`:
 
-$ bin/rubocop
+$ 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,
+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`.
 
@@ -146,4 +147,3 @@ 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.
-
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -1,5 +1,5 @@
 <!---
-This file was generated on 2019-12-05T21:32:23+00:00 from the rspec-dev repo.
+This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
 DO NOT modify it by hand as your changes will get lost the next time it is generated.
 -->
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,5 @@
 <!---
-This file was generated on 2019-12-05T21:32:23+00:00 from the rspec-dev repo.
+This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
 DO NOT modify it by hand as your changes will get lost the next time it is generated.
 -->
 
@@ -11,8 +11,8 @@ We welcome contributions from *everyone*. While contributing, please follow the
 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/rspec-rails/issues/new?template=bug_report.md)
-  - by [suggesting new features](https://github.com/rspec/rspec-rails/issues/new?template=feature_request.md)
+  - by [reporting bugs you encounter](https://github.com/rspec/rspec-rails/issues/new) with [report template](#report-template)
+  - by [suggesting new features](https://github.com/rspec/rspec-rails/issues/new)
   - by improving RSpec's [Relish](https://relishapp.com/rspec) or [API](https://rspec.info/documentation/) documentation
   - by improving [RSpec's website](https://rspec.info/) ([source](https://github.com/rspec/rspec.github.io))
   - by taking part in [feature and issue discussions](https://github.com/rspec/rspec-rails/issues)
@@ -24,47 +24,63 @@ If you need help getting started, check out the [DEVELOPMENT](DEVELOPMENT.md) fi
 
 Thanks for helping us make RSpec better!
 
-## Rspec issues labels definition
+## `Small` issues
 
-### `Your first PR` issues
+These issue are ones that we be believe are best suited for new contributors to
+get started with. They represent a meaningful contribution to the project that
+should not be too hard to pull off.
 
-These issues are the ones that we be believe are best suited for new
-contributors to get started on. They represent a potential meaningful
-contribution to the project that should not be too hard to pull off.
+## Report template
 
-### `Needs reproduction case` issues
-
-These issues are ones that have been labelled by the maintainers that we
-believe do not currently have enough information to be reproduced the RSpec
-team. While not directly counted by the GitHub contribution graph, we consider
-helping us to reproduce the issue with a repro case as an extremely meaningful
-contribution.
-
-### `Has reproduction case` issues
-
-These issues are the ones that have reproduction cases, able to start working on
-immediately. These are good ones to tackle to help us actively fix bugs.
+Having a way to reproduce your issue will be very helpful for others to help confirm,
+investigate and ultimately fix your issue. You can do this by providing an executable
+test case. To make this process easier, we have prepared one basic
+[bug report templates](REPORT_TEMPLATE.md) for you to use as a starting point.
 
 ## Maintenance branches
 
 Maintenance branches are how we manage the different supported point releases
 of RSpec. As such, while they might look like good candidates to merge into
 main, please do not open pull requests to merge them.
 
-## How do the cukes work?
-
-The cucumber features for RSpec rails document how it works, but are also quasi
-executable tests for the framework. They execute in the context of a pre-setup
-Rails app.
-
-1. Before the cucumber specs run, the directory `tmp/aruba` is cleared
-2. If the example app hasn't already been created,
-   `bundle exec rake generate:app generate:stuff` is executed.
-3. The example app is copied in to `tmp/aruba`
-4. Everything in `tmp/aruba/spec/*` is deleted apart from `spec/spec_helper.rb` and
-   `spec/rails_helper.rb`
-5. the cucumber suite executes, creating files in that app and executing them
-
-The best way to debug the app is to run a failing cucumber feature, which will
-leave the test files intact in `tmp/aruba`, then you can cd in to that director
-and run it in the bundle context of the aruba app.
+## Working on multiple RSpec gems at the same time
+
+RSpec is composed of multiple gems (`rspec-core`, `rspec-mocks`, etc). Sometimes you have
+to work on a combination of them at the same time. When submitting your code for review,
+we ask that you get a passing build (green CI). If you are working across the repositories,
+please add a commit that temporarily pins your PR to the right branch of the other repository
+you depend on. For example, if we wanted a change in `rspec-expectations` that relied on a
+change for on `rspec-mocks`. We add a commit with the title:
+
+>[WIP] Use rspec-mocks with "custom-failure-message" branch
+
+And content:
+
+```diff
+diff --git a/Gemfile b/Gemfile
+
+-%w[rspec rspec-core rspec-mocks rspec-support].each do |lib|
++%w[rspec rspec-core rspec-support].each do |lib|
+   library_path = File.expand_path("../../#{lib}", __FILE__)
+   if File.exist?(library_path) && !ENV['USE_GIT_REPOS']
+     gem lib, :path => library_path
+@@ -11,6 +11,7 @@ branch = File.read(File.expand_path("../maintenance-branch", __FILE__)).chomp
+     gem lib, :git => "https://github.com/rspec/#{lib}.git", :branch => branch
+   end
+ end
++gem 'rspec-mocks', :git => "https://github.com/rspec/rspec-mocks.git", :branch => "custom-failure-message"
+```
+
+In general the process is:
+1. Create PRs explaining what you are trying to achieve.
+2. Pin the repositories to each other.
+3. Check they pass (go green).
+4. Await review if appropriate.
+5. Remove the commit from step 2. We will merge ignoring the failure.
+6. Remove the commit from the other, check it passes with the other commit now on `main`.
+7. Merge the other.
+8. We will trigger builds for the `main` branch of affected repositories to check if everything is in order.
+
+Steps 5-8 should happen continuously (e.g. one after another but within a short timespan)
+so that we don't leave a broken main around. It is important to triage that build process
+and revert if necessary.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -1,5 +1,5 @@
 <!---
-This file was generated on 2019-12-05T21:32:23+00:00 from the rspec-dev repo.
+This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
 DO NOT modify it by hand as your changes will get lost the next time it is generated.
 -->
 
@@ -108,7 +108,7 @@ Here's a short, non-exhaustive checklist of things we typically ask contributors
 - [ ] 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`).
+- [ ] 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!)
 
@@ -129,31 +129,3 @@ $ bin/yard server --reload
 ```
 
 Then navigate to `localhost:8808` to view the rendered docs.
-
-### Publishing the documentation
-
-In the other documented rspec gems, we use a rake command in rspec-dev
-to generate documentation for [rspec.info](https://rspec.info/).
-As `rspec-rails` is no longer sync with the other gems in terms of versioning
-since `rspec-rails` 4, if you want to publish updated documentation you will
-need to run the rake task from this repository.
-
-1) First clone the `rspec.github.io` repository into a sibling folder.
-
-> `cd .. && git clone https://github.com/rspec/rspec.github.io && cd rspec.github.io`
-
-2) Check out the [source branch](https://github.com/rspec/rspec.github.io/tree/source)
-
-> `git checkout source`
-
-3) Install the template gem that will be needed as yard plugin: [rspec-docs-template](https://github.com/rspec/rspec.github.io#install-rspec-docs-template-yard-plugin).
-
-> `gem build yard-rspec-docs-template.gemspec`
-
-4) Change back to the `rspec-rails` directory
-
-> `cd ../rspec-rails`
-
-5) Generate the docs for the version you want, ensuring you are on the appropriate (released) commit.
-
-> `bundle exec rake "update_docs[4.0, 4-0-maintenance]`
diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md
@@ -0,0 +1,24 @@
+### Subject of the issue
+<!---
+Describe your issue here.
+-->
+
+### Your environment
+* Ruby version:
+* rspec-rails version:
+
+### Steps to reproduce
+<!---
+Tell us how to reproduce this issue. Please provide a working demo, you can use
+this [templates](REPORT_TEMPLATE.md) as a base.
+-->
+
+### Expected behavior
+<!---
+Tell us what should happen.
+-->
+
+### Actual behavior
+<!---
+Tell us what happens instead.
+-->
diff --git a/REPORT_TEMPLATE.md b/REPORT_TEMPLATE.md
@@ -0,0 +1,43 @@
+<!---
+This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
+DO NOT modify it by hand as your changes will get lost the next time it is generated.
+-->
+
+# Report template
+
+```ruby
+# frozen_string_literal: true
+
+begin
+  require "bundler/inline"
+rescue LoadError => e
+  $stderr.puts "Bundler version 1.10 or later is required. Please update your Bundler"
+  raise e
+end
+
+gemfile(true) do
+  source "https://rubygems.org"
+
+  gem "rspec", "3.7.0" # Activate the gem and version you are reporting the issue against.
+end
+
+puts "Ruby version is: #{RUBY_VERSION}"
+require 'rspec/autorun'
+
+RSpec.describe 'additions' do
+  it 'returns 2' do
+    expect(1 + 1).to eq(2)
+  end
+
+  it 'returns 1' do
+    expect(3 - 1).to eq(-1)
+  end
+end
+```
+
+Simply copy the content of the appropriate template into a `.rb` file on your computer
+and make the necessary changes to demonstrate the issue. You can execute it by running
+`ruby rspec_report.rb` in your terminal.
+
+You can then share your executable test case as a [gist](https://gist.github.com), or
+simply paste the content into the issue description.

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# This file was generated on 2020-12-23T21:24:00+01:00 from the rspec-dev repo.`
	`1`	`+# This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.`
`2`	`2`	`# DO NOT modify it by hand as your changes will get lost the next time it is generated.`
`3`	`3`
`4`	`4`	`github: [JonRowe, benoittgt]`