Skip to content

Commit a1fba38

Browse files
JonRoweJonRowe
committed
Updated common plaintext files (from rspec-dev) main
1 parent d566851 commit a1fba38

File tree

5 files changed

+64
-89
lines changed

5 files changed

+64
-89
lines changed

‎.github/FUNDING.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
1+
# This file was generated on 2023-04-16T20:43:00+01:00 from the rspec-dev repo.
22
# DO NOT modify it by hand as your changes will get lost the next time it is generated.
33

44
github: [JonRowe, benoittgt]

‎BUILD_DETAIL.md

Lines changed: 3 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
<!---
2-
This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
2+
This file was generated on 2023-04-16T20:43:00+01: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

66
# The CI build, in detail
77

8-
The CI build runs many verification steps to prevent regressions and
8+
The [Travis CI build](https://travis-ci.org/rspec/rspec-rails)
9+
runs many verification steps to prevent regressions and
910
ensure high-quality code. To run the Travis build locally, run:
1011

1112
```
@@ -65,21 +66,6 @@ $ bundle exec cucumber
6566
$ bin/cucumber
6667
```
6768

68-
## Snippets
69-
70-
RSpec Rails uses snippets, self-contained examples that are used to cover
71-
cases and regressions that don't need a full-blown example application to
72-
reproduce.
73-
74-
Snippets reuse the already installed gems, and don't attempt to install gem
75-
versions that are not on the system already to prevent version mismatches.
76-
77-
Run with:
78-
79-
```
80-
$ script/run_snippets.sh
81-
```
82-
8369
## YARD documentation
8470

8571
RSpec uses [YARD](https://yardoc.org/) for API documentation on the [rspec.info site](https://rspec.info/).

‎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 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
2+
This file was generated on 2023-04-16T20:43:00+01: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

‎CONTRIBUTING.md

Lines changed: 54 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
2+
This file was generated on 2023-04-16T20:43:00+01: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

@@ -11,9 +11,9 @@ We welcome contributions from *everyone*. While contributing, please follow the
1111
If you'd like to help make RSpec better, here are some ways you can contribute:
1212

1313
- by running RSpec HEAD to help us catch bugs before new releases
14-
- by [reporting bugs you encounter](https://github.com/rspec/rspec-rails/issues/new?template=bug_report.md)
15-
- by [suggesting new features](https://github.com/rspec/rspec-rails/issues/new?template=feature_request.md)
16-
- by improving RSpec's [Gherkin](https://rspec.info/documentation/) or [API](https://rspec.info/documentation/) documentation
14+
- by [reporting bugs you encounter](https://github.com/rspec/rspec-rails/issues/new) with [report template](#report-template)
15+
- by [suggesting new features](https://github.com/rspec/rspec-rails/issues/new)
16+
- by improving RSpec's Feature or API [documentation](https://rspec.info/documentation/)
1717
- by improving [RSpec's website](https://rspec.info/) ([source](https://github.com/rspec/rspec.github.io))
1818
- by taking part in [feature and issue discussions](https://github.com/rspec/rspec-rails/issues)
1919
- by adding a failing test for reproducible [reported bugs](https://github.com/rspec/rspec-rails/issues)
@@ -24,47 +24,63 @@ If you need help getting started, check out the [DEVELOPMENT](DEVELOPMENT.md) fi
2424

2525
Thanks for helping us make RSpec better!
2626

27-
## Rspec issues labels definition
27+
## `Small` issues
2828

29-
### `Your first PR` issues
29+
These issue are ones that we be believe are best suited for new contributors to
30+
get started with. They represent a meaningful contribution to the project that
31+
should not be too hard to pull off.
3032

31-
These issues are the ones that we be believe are best suited for new
32-
contributors to get started on. They represent a potential meaningful
33-
contribution to the project that should not be too hard to pull off.
33+
## Report template
3434

35-
### `Needs reproduction case` issues
36-
37-
These issues are ones that have been labelled by the maintainers that we
38-
believe do not currently have enough information to be reproduced the RSpec
39-
team. While not directly counted by the GitHub contribution graph, we consider
40-
helping us to reproduce the issue with a repro case as an extremely meaningful
41-
contribution.
42-
43-
### `Has reproduction case` issues
44-
45-
These issues are the ones that have reproduction cases, able to start working on
46-
immediately. These are good ones to tackle to help us actively fix bugs.
35+
Having a way to reproduce your issue will be very helpful for others to help confirm,
36+
investigate and ultimately fix your issue. You can do this by providing an executable
37+
test case. To make this process easier, we have prepared one basic
38+
[bug report templates](REPORT_TEMPLATE.md) for you to use as a starting point.
4739

4840
## Maintenance branches
4941

5042
Maintenance branches are how we manage the different supported point releases
5143
of RSpec. As such, while they might look like good candidates to merge into
5244
main, please do not open pull requests to merge them.
5345

54-
## How do the cukes work?
55-
56-
The cucumber features for RSpec rails document how it works, but are also quasi
57-
executable tests for the framework. They execute in the context of a pre-setup
58-
Rails app.
59-
60-
1. Before the cucumber specs run, the directory `tmp/aruba` is cleared
61-
2. If the example app hasn't already been created,
62-
`bundle exec rake generate:app generate:stuff` is executed.
63-
3. The example app is copied in to `tmp/aruba`
64-
4. Everything in `tmp/aruba/spec/*` is deleted apart from `spec/spec_helper.rb` and
65-
`spec/rails_helper.rb`
66-
5. the cucumber suite executes, creating files in that app and executing them
67-
68-
The best way to debug the app is to run a failing cucumber feature, which will
69-
leave the test files intact in `tmp/aruba`, then you can cd in to that director
70-
and run it in the bundle context of the aruba app.
46+
## Working on multiple RSpec gems at the same time
47+
48+
RSpec is composed of multiple gems (`rspec-core`, `rspec-mocks`, etc). Sometimes you have
49+
to work on a combination of them at the same time. When submitting your code for review,
50+
we ask that you get a passing build (green CI). If you are working across the repositories,
51+
please add a commit that temporarily pins your PR to the right branch of the other repository
52+
you depend on. For example, if we wanted a change in `rspec-expectations` that relied on a
53+
change for on `rspec-mocks`. We add a commit with the title:
54+
55+
>[WIP] Use rspec-mocks with "custom-failure-message" branch
56+
57+
And content:
58+
59+
```diff
60+
diff --git a/Gemfile b/Gemfile
61+
62+
-%w[rspec rspec-core rspec-mocks rspec-support].each do |lib|
63+
+%w[rspec rspec-core rspec-support].each do |lib|
64+
library_path = File.expand_path("../../#{lib}", __FILE__)
65+
if File.exist?(library_path) && !ENV['USE_GIT_REPOS']
66+
gem lib, :path => library_path
67+
@@ -11,6 +11,7 @@ branch = File.read(File.expand_path("../maintenance-branch", __FILE__)).chomp
68+
gem lib, :git => "https://github.com/rspec/#{lib}.git", :branch => branch
69+
end
70+
end
71+
+gem 'rspec-mocks', :git => "https://github.com/rspec/rspec-mocks.git", :branch => "custom-failure-message"
72+
```
73+
74+
In general the process is:
75+
1. Create PRs explaining what you are trying to achieve.
76+
2. Pin the repositories to each other.
77+
3. Check they pass (go green).
78+
4. Await review if appropriate.
79+
5. Remove the commit from step 2. We will merge ignoring the failure.
80+
6. Remove the commit from the other, check it passes with the other commit now on `main`.
81+
7. Merge the other.
82+
8. We will trigger builds for the `main` branch of affected repositories to check if everything is in order.
83+
84+
Steps 5-8 should happen continuously (e.g. one after another but within a short timespan)
85+
so that we don't leave a broken main around. It is important to triage that build process
86+
and revert if necessary.

‎DEVELOPMENT.md

Lines changed: 5 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!---
2-
This file was generated on 2020-12-25T18:48:30+00:00 from the rspec-dev repo.
2+
This file was generated on 2023-04-16T20:43:00+01: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

@@ -85,8 +85,9 @@ gem declarations. The `Gemfile` evaluates that file if it exists, and it is git-
8585

8686
# Running the build
8787

88-
The CI build runs many verification steps to prevent regressions and
89-
ensure high-quality code. To run the build locally, run:
88+
The [Travis CI build](https://travis-ci.org/rspec/rspec-rails)
89+
runs many verification steps to prevent regressions and
90+
ensure high-quality code. To run the Travis build locally, run:
9091

9192
```
9293
$ script/run_build
@@ -107,7 +108,7 @@ Here's a short, non-exhaustive checklist of things we typically ask contributors
107108
- [ ] New behavior is covered by tests and all tests are passing.
108109
- [ ] No Ruby warnings are issued by your changes.
109110
- [ ] Documentation reflects changes and renders as intended.
110-
- [ ] Rubocop passes (e.g. `bundle exec rubocop`).
111+
- [ ] RuboCop passes (e.g. `bundle exec rubocop lib`).
111112
- [ ] Commits are squashed into a reasonable number of logical changesets that tell an easy-to-follow story.
112113
- [ ] No changelog entry is necessary (we'll add it as part of the merge process!)
113114

@@ -128,31 +129,3 @@ $ bin/yard server --reload
128129
```
129130

130131
Then navigate to `localhost:8808` to view the rendered docs.
131-
132-
### Publishing the documentation
133-
134-
In the other documented rspec gems, we use a rake command in rspec-dev
135-
to generate documentation for [rspec.info](https://rspec.info/).
136-
As `rspec-rails` is no longer sync with the other gems in terms of versioning
137-
since `rspec-rails` 4, if you want to publish updated documentation you will
138-
need to run the rake task from this repository.
139-
140-
1) First clone the `rspec.github.io` repository into a sibling folder.
141-
142-
> `cd .. && git clone https://github.com/rspec/rspec.github.io && cd rspec.github.io`
143-
144-
2) Check out the [source branch](https://github.com/rspec/rspec.github.io/tree/source)
145-
146-
> `git checkout source`
147-
148-
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).
149-
150-
> `gem build yard-rspec-docs-template.gemspec`
151-
152-
4) Change back to the `rspec-rails` directory
153-
154-
> `cd ../rspec-rails`
155-
156-
5) Generate the docs for the version you want, ensuring you are on the appropriate (released) commit.
157-
158-
> `bundle exec rake "update_docs[4.0, 4-0-maintenance]`

0 commit comments

Comments
 (0)