Elliot Winkler
parent
9400e892a0
commit
147ec58fa7
|
|
@ -1,10 +1,10 @@
|
|||
# Contributing to Shoulda Matchers
|
||||
|
||||
We've put a lot of work into making improvements to Shoulda Matchers, but we
|
||||
always welcome changes and improvements from the community!
|
||||
Although we are always happy to make improvements to Shoulda Matchers, we also
|
||||
welcome changes and improvements from the community!
|
||||
|
||||
Have a fix for a problem you've been running into or an idea for a new feature
|
||||
you think would be useful? Simply follow these instructions:
|
||||
you think would be useful? Here's what you need to do:
|
||||
|
||||
1. [Read and understand the Code of Conduct](#code-of-conduct).
|
||||
1. Fork this repo and clone your fork to somewhere on your machine.
|
||||
|
|
@ -72,8 +72,10 @@ you'll be most interested in.
|
|||
|
||||
In addition, tests are broken up into two categories:
|
||||
|
||||
* `spec/unit`
|
||||
* `spec/acceptance`
|
||||
* `spec/unit` — low-level tests for individual matchers (you're probably
|
||||
interested in these)
|
||||
* `spec/acceptance` — high-level tests to ensure that the gem works in Rails
|
||||
projects, plain Ruby projects, etc. (these do not need to get updated often)
|
||||
|
||||
A word about the tests, by the way: they're admittedly the most complicated part
|
||||
of this gem, and there are a few different strategies that we've introduced at
|
||||
|
|
@ -104,22 +106,43 @@ some key differences:
|
|||
|
||||
## Running tests
|
||||
|
||||
### A word about Appraisals
|
||||
|
||||
Because the gem supports multiple Ruby and Rails versions, we have to be able
|
||||
to test against them as well.
|
||||
|
||||
Oftentimes it is enough to use whatever Ruby version you have on your computer,
|
||||
but if you are fixing a bug that targets a specific Ruby version, you'll want to
|
||||
make sure to switch to that using your Ruby manager of choice before you run any
|
||||
tests.
|
||||
|
||||
If you are fixing a bug for a specific _Rails_ version, then you'll want to use
|
||||
a specific "appraisal" when running a test. [Appraisals] are Gemfiles centered
|
||||
around a Rails version. What this means is that when running tests, you have to
|
||||
specify which one to use. You do this by using this command:
|
||||
|
||||
```bash
|
||||
bundle exec appraisal <appraisal name> ...
|
||||
```
|
||||
|
||||
You can find the available list of appraisals by running:
|
||||
|
||||
```bash
|
||||
bundle exec appraisal list
|
||||
```
|
||||
|
||||
[Appraisals]: https://github.com/thoughtbot/appraisal
|
||||
|
||||
### Unit tests
|
||||
|
||||
Unit tests are the most common kind of tests in the gem. They exercise matcher
|
||||
code file by file in the context of a real Rails application. This application
|
||||
is created and loaded every time you run `rspec`. Because of this, it can be
|
||||
expensive to run individual tests. To save time, the best way to run unit tests
|
||||
is by using [Zeus].
|
||||
is created and loaded every time you start running tests.
|
||||
|
||||
[Zeus]: https://github.com/burke/zeus
|
||||
|
||||
You'll want to start by running `zeus start` in one shell. Then in another
|
||||
shell, instead of using `bundle exec rspec` to run tests, you'll use `bundle
|
||||
exec zeus rspec`. So for instance, you might say:
|
||||
To run a unit test, you might say something like:
|
||||
|
||||
```bash
|
||||
bundle exec zeus rspec spec/unit/shoulda/matchers/active_model/validate_inclusion_of_matcher_spec.rb
|
||||
bundle exec appraisal 5.2 rspec spec/unit/shoulda/matchers/active_model/validate_inclusion_of_matcher_spec.rb
|
||||
```
|
||||
|
||||
### Acceptance tests
|
||||
|
|
@ -128,29 +151,10 @@ The acceptance tests exercise matchers in the context of a real Ruby or Rails
|
|||
application. Unlike unit tests, this application is set up and torn down for
|
||||
each test.
|
||||
|
||||
Whereas you make use of Zeus to run unit tests, you make use of Appraisal for
|
||||
acceptance tests. [Appraisal] lets you run tests against multiple versions of
|
||||
Rails and Ruby, and in fact, this is baked into the test suite. This means that
|
||||
if you're trying to run a single test file, you'll need to specify which
|
||||
appraisal to use. For instance, you can't simply say:
|
||||
|
||||
[Appraisal]: https://github.com/thoughtbot/appraisal
|
||||
To run an acceptance test, you might say something like:
|
||||
|
||||
```bash
|
||||
bundle exec rspec spec/acceptance/active_model_integration_spec.rb
|
||||
```
|
||||
|
||||
Instead, you need to say:
|
||||
|
||||
```bash
|
||||
bundle exec appraisal 5.1 rspec spec/acceptance/active_model_integration_spec.rb
|
||||
```
|
||||
|
||||
You can get a list of valid appraisals by running the following command and
|
||||
inspecting the output:
|
||||
|
||||
```bash
|
||||
bundle exec appraisal --help
|
||||
bundle exec appraisal 5.2 rspec spec/acceptance/rails_integration_spec.rb
|
||||
```
|
||||
|
||||
### All tests
|
||||
|
|
@ -167,7 +171,7 @@ bundle exec rake
|
|||
guide] was a wonderful piece on this topic when it came out and we still find
|
||||
it to be helpful even today.
|
||||
* Squash "WIP" commits and remove merge commits by rebasing your branch against
|
||||
`master`. We try to keep our commit history as clean as possible. so we really
|
||||
`master`. We try to keep our commit history as clean as possible.
|
||||
|
||||
[Tim Pope's guide]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
|
||||
|
||||
|
|
@ -188,7 +192,7 @@ updating the API, it helps us greatly to update the docs at the same time.
|
|||
|
||||
You may also notice that we have a changelog in the form of [NEWS.md](NEWS.md).
|
||||
You may be tempted to include changes to this in your branch, but don't worry
|
||||
about this -- we'll take care of it!
|
||||
about this — we'll take care of it!
|
||||
|
||||
## Continuous integration
|
||||
|
||||
|
|
@ -196,16 +200,15 @@ While running `bundle exec rake` is a great way to check your work, this command
|
|||
will only run your tests against the latest supported Ruby and Rails version.
|
||||
Ultimately, though, you'll want to ensure that your changes work in all possible
|
||||
environments. We make use of [Travis][travis] to do this work for us. Travis
|
||||
will kick in after you push up a branch or open a PR. It takes 15-20 minutes to
|
||||
will kick in after you push up a branch or open a PR. It takes 20-30 minutes to
|
||||
run a complete build, which you are free to
|
||||
[monitor as it progresses][shoulda-matchers-on-travis].
|
||||
|
||||
[shoulda-matchers-on-travis]: https://travis-ci.org/thoughtbot/shoulda-matchers
|
||||
|
||||
So what happens if the build fails in some way? Don't fear! Click on a failed
|
||||
job and scroll through its output to determine the cause of the failure. You'll
|
||||
want to make changes to your branch and push them up until the entire build is
|
||||
green. It may take a bit of time, but overall it is worth it and it helps us
|
||||
immensely!
|
||||
What happens if the build fails in some way? Don't fear! Click on a failed job
|
||||
and scroll through its output to determine the cause of the failure. You'll want
|
||||
to make changes to your branch and push them up until the entire build is green.
|
||||
It may take a bit of time, but overall it is worth it and it helps us immensely!
|
||||
|
||||
[travis]: https://travis-ci.org/
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ be too low-level for contributors.
|
|||
|
||||
## Communication
|
||||
|
||||
We use a combination of methods to communicate with each other:
|
||||
We have several ways that we can communicate with each other:
|
||||
|
||||
* In planning major releases, it can be helpful to create a **new issue**
|
||||
outlining the changes as well as steps needed to launch the release. This
|
||||
|
|
@ -53,9 +53,9 @@ workflow is as follows:
|
|||
Besides the matchers, there are files in `lib` which you may need to reference
|
||||
or update:
|
||||
|
||||
* `lib/shoulda/matchers/doublespeak*` -- a small handrolled mocking library
|
||||
* `lib/shoulda/matchers/doublespeak*` — a small handrolled mocking library
|
||||
which is used by the `permit` matcher
|
||||
* `lib/shoulda/matchers/util*` -- extra methods which are used in various places
|
||||
* `lib/shoulda/matchers/util*` — extra methods which are used in various places
|
||||
to detect library versions, wrap/indent text, and more
|
||||
|
||||
## Updating the changelog
|
||||
|
|
@ -113,11 +113,14 @@ open doc/index.html
|
|||
The docfiles that YARD generates are published to the docsite, which is located
|
||||
at:
|
||||
|
||||
<https://matchers.shoulda.io/docs>
|
||||
<https://matchers.shoulda.io>
|
||||
|
||||
The docsite is hosted on GitHub Pages*. As such, the `gh-pages` branch hosts the
|
||||
code for the docsite. This branch is written to automatically by the
|
||||
`docs:publish` and `docs:publish_latest` tasks.
|
||||
The docsite is hosted on GitHub Pages*. As such, the `gh-pages` branch hosts its
|
||||
code. Usually you don't need to update this branch directly unless you want to
|
||||
make changes to the homepage itself. As for the *documentation*, it is hosted
|
||||
one level deeper:
|
||||
|
||||
<https://matchers.shoulda.io/docs>
|
||||
|
||||
The URL above actually links to a bare-bones HTML page which merely serves to
|
||||
automatically redirect the visitor to the docs for the latest published version
|
||||
|
|
@ -174,7 +177,7 @@ Releasing a new version is very simple:
|
|||
### Re-publishing docs
|
||||
|
||||
In general you'll use the `release` task to update the docsite, but there may be
|
||||
a situation where you'll need to do it manually.
|
||||
situations where you'll need to do it manually.
|
||||
|
||||
You can re-publish the docs for the latest version (as governed by
|
||||
`lib/shoulda/matchers/version.rb`) by running:
|
||||
|
|
@ -183,13 +186,13 @@ You can re-publish the docs for the latest version (as governed by
|
|||
bundle exec rake docs:publish_latest
|
||||
```
|
||||
|
||||
This will update the version to which the docsite auto-redirects to the latest
|
||||
version. For instance, if the latest version were 4.0.0, this command would
|
||||
publish the docs at <https://matchers.shoulda.io/docs/v4.0.0> but redirect
|
||||
This will update the auto-redirect on the index page to the latest version. For
|
||||
instance, if the latest version were 4.0.0, this command would publish the docs
|
||||
at <https://matchers.shoulda.io/docs/v4.0.0> and simultaneously redirect
|
||||
<https://matchers.shoulda.io/docs> to this location.
|
||||
|
||||
However, if you want to publish the docs for a version and at the same
|
||||
time manually set the auto-redirected version, you can run this instead:
|
||||
However, if you want to publish the docs for a version but manually set the
|
||||
auto-redirected version, you can run this instead:
|
||||
|
||||
```bash
|
||||
bundle exec rake docs:publish[version, latest_version]
|
||||
|
|
@ -208,9 +211,9 @@ This would publish the docs for 4.0.0 at
|
|||
|
||||
## Addendum: Labels
|
||||
|
||||
In order to corral the issue and PR backlog, we've found
|
||||
[labels] to be useful for cataloguing and tracking progress purposes. Over time
|
||||
we've added quite a collection of labels. Here's a quick list:
|
||||
Considering that we work on the gem in our spare time, we've found [labels] to
|
||||
be useful for cataloguing and marking progress. Over time we've added quite a
|
||||
collection of labels. Here's a quick list:
|
||||
|
||||
[labels]: https://github.com/thoughtbot/shoulda-matchers/labels
|
||||
|
||||
|
|
@ -218,24 +221,24 @@ we've added quite a collection of labels. Here's a quick list:
|
|||
|
||||
* **Issue: Bug**
|
||||
* **Issue: Feature Request**
|
||||
* **Issue: Need to Investigate** -- if we don't know whether a bug is legitimate
|
||||
* **Issue: Need to Investigate** — if we don't know whether a bug is legitimate
|
||||
or not
|
||||
* **Issue: PR Needed** -- perhaps unnecessary, but it does signal to the
|
||||
* **Issue: PR Needed** — perhaps unnecessary, but it does signal to the
|
||||
community that we'd love a PR
|
||||
|
||||
### Labels for PRs
|
||||
|
||||
* **PR: Bugfix**
|
||||
* **PR: Feature**
|
||||
* **PR: Good to Merge** -- most of the time not necessary, but can be helpful in
|
||||
* **PR: Good to Merge** — most of the time not necessary, but can be helpful in
|
||||
a code freeze before a release to mark PRs that we will include in the next
|
||||
release
|
||||
* **PR: In Progress** -- used to mark PRs that are still being worked on by the
|
||||
* **PR: In Progress** — used to mark PRs that are still being worked on by the
|
||||
PR author
|
||||
* **PR: Needs Documentation**
|
||||
* **PR: Needs Review**
|
||||
* **PR: Needs Tests**
|
||||
* **PR: Needs Updates Before Merge** -- along the same lines as the other
|
||||
* **PR: Needs Updates Before Merge** — along the same lines as the other
|
||||
"Needs" tags, but more generic
|
||||
|
||||
### Generic labels
|
||||
|
|
|
|||
Loading…
Reference in New Issue