shoulda-matchers 3.1.3 → 4.0.0.rc1

data/MAINTAINING.md

@@ -0,0 +1,250 @@
+# Maintaining Shoulda Matchers
+
+As maintainers of the gem, this is our guide. Most of the steps and guidelines
+in the [Contributing](CONTRIBUTING.md) document apply here, including how to set
+up your environment, write code to fit the code style, run tests, craft commits
+and manage branches. Beyond this, this document provides some details that would
+be too low-level for contributors.
+
+## Communication
+
+We use a combination of methods to 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
+  serves both as an announcement to the community as well as an area to keep a
+  checklist.
+* To track progress for the next release, **GitHub milestones** are useful.
+* To track progress on the movement of issues, [**labels**](#addendum-labels)
+  are useful.
+* To communicate small-scale changes, **pull requests** are effective, as
+  mentioned above.
+* To communicate large-scale changes or explain topics, **email** is best.
+
+## Managing the community
+
+As anyone who has played a sim game before, it's important to make your patrons
+happy. We do this by:
+
+* Answering questions from members of the community
+* Closing stale issues and feature requests
+* Keeping the community informed by ensuring that the changelog is up to date
+* Ensuring that the inline documentation, as well as the docsite, is kept up to
+  date
+
+## Workflow
+
+We generally follow [GitHub Flow]. The `master` branch is the main line, and all
+branches are cut from and get merged back into this branch. Generally, the
+workflow is as follows:
+
+[GitHub Flow]: https://help.github.com/articles/github-flow/
+
+* Cut a feature or bugfix branch from this branch.
+* Upon completing a branch, create a PR and ask another maintainer to approve
+  it.
+* Try to keep the commit history as clean as possible. Before merging, squash
+  "WIP" or related commits together and rebase as needed.
+* Once your PR is approved and you've cleaned up your branch, you're free to
+  merge it in.
+
+## Architecture
+
+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
+  which is used by the `permit` matcher
+* `lib/shoulda/matchers/util*` -- extra methods which are used in various places
+  to detect library versions, wrap/indent text, and more
+
+## Updating the changelog
+
+After every user-facing change makes it into master, we make a note of it in the
+changelog, which for historical reasons is kept in `NEWS.md`. The changelog is
+sorted in reverse order by release version, with the topmost version as the next
+release (tagged as "(Unreleased)").
+
+Within each version, there are five available categories you can divide changes
+into. They are all optional but they should appear in this order:
+
+1. Backward-compatible changes
+1. Deprecations
+1. Bug fixes
+1. Features
+1. Improvements
+
+Within each category section, the changes relevant to that category are listed
+in chronological order.
+
+For each change, provide a human-readable description of the change as well as a
+linked reference to the PR where that change emerged (or the commit ID if no
+such PR is available). This helps users cross-reference changes if they need to.
+
+## Documentation
+
+### Generating documentation
+
+As mentioned in the Contributing document, we use YARD for documentation. YARD
+is configured via `.yardopts` to process the Ruby files in `lib/` as well as
+`NEWS.md` and the Markdown files in `docs/` and write the documentation in HTML
+form to `doc`. This command will do exactly that:
+
+```bash
+bundle exec yard doc
+```
+
+However, if you're actively updating the documentation, it's more helpful to
+launch a process that will watch the aforementioned source files for changes and
+generate the HTML for you automatically:
+
+```bash
+bundle exec rake docs:autogenerate
+```
+
+Whichever approach you take, you can view the generated docs locally by running:
+
+```bash
+open doc/index.html
+```
+
+### About the docsite
+
+The docfiles that YARD generates are published to the docsite, which is located
+at:
+
+<https://matchers.shoulda.io/docs>
+
+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 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
+of the gem. This version is hardcoded in the HTML page, but is also updated
+automatically by the `docs:publish` and `docs:publish_latest` tasks.
+
+*\* thoughtbot owns <https://shoulda.io>, and
+they've got `matchers.shoulda.io` set up on the DNS level as an alias for
+`thoughtbot.github.io/shoulda-matchers`.*
+
+## Versioning
+
+### Naming a new version
+
+As designated in the README, we follow [SemVer 2.0][semver]. This offers a
+meaningful baseline for deciding how to name versions. Generally speaking:
+
+[semver]: https://semver.org/spec/v2.0.0.html
+
+* We bump the "major" part of the version if we're introducing
+  backward-incompatible changes (e.g. changing the API or core behavior,
+  removing parts of the API, or dropping support for a version of Ruby).
+* We bump the "minor" part if we're adding a new feature (e.g. adding a new
+  matcher or adding a new qualifier to a matcher).
+* We bump the "patch" part if we're merely including bugfixes.
+
+In addition to major, minor, and patch levels, you can also append a
+suffix to the version for pre-release versions. We usually use this to issue
+release candidates prior to an actual release. A version number in this case
+might look like `4.0.0.rc1`.
+
+### Releasing a new version
+
+Releasing a new version is very simple:
+
+1. First, you'll want to be given ownership permissions for the Ruby gem itself.
+   If you want to give someone else these rights, you can use:
+
+   ```bash
+   gem owner shoulda-matchers -a <email address>
+   ```
+1. Next, you'll want to update the `VERSION` constant in
+   `lib/shoulda/matchers/version.rb`. This constant is referenced in the gemspec
+   and is used in the Rake tasks to publish the gem on RubyGems as well as
+   generate documentation.
+1. Finally, you'll want to run:
+
+   ```bash
+   rake release
+   ```
+
+   This will not only push the gem to RubyGems, but also update the docsite.
+
+### 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.
+
+You can re-publish the docs for the latest version (as governed by
+`lib/shoulda/matchers/version.rb`) by running:
+
+```bash
+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
+<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:
+
+```bash
+bundle exec rake docs:publish[version, latest_version]
+```
+
+Here, `version` and `latest_version` are both version strings. For instance, you
+might say:
+
+```bash
+bundle exec rake docs:publish[4.0.0, 3.7.2]
+```
+
+This would publish the docs for 4.0.0 at
+<https://matchers.shoulda.io/docs/v4.0.0>, but redirect
+<https://matchers.shoulda.io/docs> to <https://matchers.shoulda.io/docs/v3.7.2>.
+
+## 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:
+
+[labels]: https://github.com/thoughtbot/shoulda-matchers/labels
+
+### Labels for issues
+
+* **Issue: Bug**
+* **Issue: Feature Request**
+* **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
+  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
+  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 author
+* **PR: Needs Documentation**
+* **PR: Needs Review**
+* **PR: Needs Tests**
+* **PR: Needs Updates Before Merge** -- along the same lines as the other
+  "Needs" tags, but more generic
+
+### Generic labels
+
+* **Blocked**
+* **Documentation**
+* **Needs Decision**
+* **Needs Revisiting**
+* **Question**
+* **Rails X**
+* **Ruby X.Y**
+* **UX**

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2016, Tammer Saleh, thoughtbot, inc.
+Copyright (c) 2006-2018, Tammer Saleh and thoughtbot, inc.
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/NEWS.md

@@ -1,15 +1,183 @@
-# 3.1.3
+# 4.0.0 (unreleased)
+
+This release mainly brings the gem up to date with modern versions of Ruby and
+Rails and drops support for older, unsupported versions. The compatibility list
+is now:
+
+* **Ruby:** 2.5.1, 2.4.4, 2.3.7, 2.2.8
+* **Rails:** 5.2.1, 5.1.6, 5.0.6, 4.2.9
+
+### Backward-incompatible changes
+
+* Drop support for Rails 4.0 and 4.1 as well as Ruby 2.0 and 2.1, since they've
+  been end-of-lifed. The gem now supports Ruby 2.2+ and Rails 4.2+.
+
+* `use_before_filter`, `use_after_filter`, and `use_around_filter` are no longer
+  usable when using shoulda-matchers under Rails 5.x, as the corresponding
+  controller callbacks don't exist there.
+
+  * *PR: [#1054]*
+
+### Deprecations
+
+* `define_enum_for`: `with` is deprecated in favor of `with_values`. This is to
+  prevent confusion with `with_prefix` and `with_suffix`, which are new.
+
+  * *PR: [#1077]*
+
+### Bug fixes
+
+* Fix association matchers when used under Rails 5.x so that they make use of
+  `ActiveRecord::Base.connection.data_sources` instead of
+  `ActiveRecord::Base.connection.tables`, which was deprecated.
+
+  * *Commit: [61c3654]*
+  * *PR: [#943]*
+  * *Original issue: [#933]*
+
+* Fix the `serialize` matcher so that it works with Rails 5.x.
+
+  * *Commit: [df04f87]*
+  * *PR: [#965]*
+  * *Original issue: [#913]*
+
+* Fix our custom mocking library Doublespeak, which is used by
+  `delegate_method`, so that it does not produce a warning under Ruby 2.4.
+
+  * *Commit: [8d7dcb8]*
+  * *PR: [#1038]*
+  * *Original issue: [#1006]*
+
+* Fix the `permit` matcher so that it uses the correct method signature to call
+  the controller action with params in order to prevent a warning under Rails
+  5.x.
+
+  * *Commit: [ce9624b]*
+  * *PRs: [#989], [#964], [#917]*
+  * *Original issue: [#867]*
+
+* Fix the `define_enum_for` matcher so that it once more allows string columns
+  to be used as enum attributes.
+
+  * *Commit: [5650aae]*
+  * *PR: [#1063]*
+  * *Original issue: [#912]*
+
+* Fix `validate_uniqueness_of` when used under Rails 4.2 so that when the
+  attribute you're testing is a boolean column, it will no longer emit a
+  warning.
+
+  * *PR: [#1073]*
+  * *Original issue: [#949]*
+
+* Fix `validate_inclusion_of` so that if it fails, it will no longer blow up
+  with the error "undefined method \`attribute_setter' for nil:NilClass".
+
+  * *Original issue: [#904]*
+
+* Add negative versions of all validation matchers (i.e. implement
+  `does_not_match?` for them) to prevent them from blowing up with
+  "undefined method \`attribute_setter' for nil:NilClass".
+
+  * *Original issue: [#904]*
+
+### Features
+
+* Add `required` and `optional` qualifiers to `belong_to` and `have_one`
+  matchers. (When using the `belong_to` matcher under Rails 5+, `required` is
+  assumed unless overridden.)
+
+  * *Commit: [3af3d9f]*
+  * *Original PR: [#956]*
+  * *Original issues: [#870], [#861]*
+
+* Add `allow_nil` qualifier to `delegate_method`.
+
+  * *Commit: [d49cfca]*
+  * *Original PR: [#798]*
+
+* Add `allow_nil` qualifier to `validate_length_of`.
+
+  * *Original PR: [#724]*
+
+* Add a `port` option to the `route` matcher to allow testing a route that has
+  a constraint on it such that only a specific port may be used to access that
+  route.
+
+  * *PRs: [#1074], [#1075]*
+  * *Original issue: [#954]*
+
+* Add `with_prefix` and `with_suffix` to `define_enum_for` to allow testing
+  the `enum` macro with corresponding `prefix` and `suffix` options (Rails 5
+  only).
+
+  * *PR: [#1077]
+  * *Original issue: [#961]
+
+* Add `index_errors` option to `has_many` (Rails 5 only).
+
+  * *Commit: [795ca68]*
+  * *PR: [#1089]*
+
+[a6d09aa]: https://github.com/thoughtbot/shoulda-matchers/commit/a6d09aa5de0d546367e7b3d7177dfde6c66f7f05
+[#943]: https://github.com/thoughtbot/shoulda-matchers/pulls/943
+[#933]: https://github.com/thoughtbot/shoulda-matchers/issues/933
+[df04f87]: https://github.com/thoughtbot/shoulda-matchers/commit/df04f8704abc3754c63c488433dac8c30573da6b
+[#965]: https://github.com/thoughtbot/shoulda-matchers/pulls/965
+[#913]: https://github.com/thoughtbot/shoulda-matchers/issues/913
+[8d7dcb8]: https://github.com/thoughtbot/shoulda-matchers/commit/8d7dcb88c3bae8315e4107a39ae17fe19a4b6786
+[#1038]: https://github.com/thoughtbot/shoulda-matchers/pulls/1038
+[#1006]: httpce9624b3c5a08b9134150e228440c771d95782b7s://github.com/thoughtbot/shoulda-matchers/issues/1006
+[ce9624b]: https://github.com/thoughtbot/shoulda-matchers/commit/ce9624b3c5a08b9134150e228440c771d95782b7
+[#989]: https://github.com/thoughtbot/shoulda-matchers/pulls/989
+[#964]: https://github.com/thoughtbot/shoulda-matchers/pulls/964
+[#917]: https://github.com/thoughtbot/shoulda-matchers/pulls/917
+[#867]: https://github.com/thoughtbot/shoulda-matchers/issues/867
+[#1054]: https://github.com/thoughtbot/shoulda-matchers/pulls/1054
+[5650aae]: https://github.com/thoughtbot/shoulda-matchers/commit/5650aae35de85aeabd75bc544324fda33ce1a092
+[#1063]: https://github.com/thoughtbot/shoulda-matchers/pulls/1063
+[#912]: https://github.com/thoughtbot/shoulda-matchers/issues/912
+[#1073]: https://github.com/thoughtbot/shoulda-matchers/pulls/1073
+[#949]: https://github.com/thoughtbot/shoulda-matchers/issues/949
+[d49cfca]: https://github.com/thoughtbot/shoulda-matchers/commit/d49cfcae1b294e12a05e06a5612cb8ebb22a7df1
+[#798]: https://github.com/thoughtbot/shoulda-matchers/pulls/798
+[#724]: https://github.com/thoughtbot/shoulda-matchers/issues/724
+[d49cfca]: https://github.com/thoughtbot/shoulda-matchers/commit/d49cfcae1b294e12a05e06a5612cb8ebb22a7df1
+[3af3d9f]: https://github.com/thoughtbot/shoulda-matchers/commit/3af3d9f7abb768c063759941724ccae48c7b76d6
+[#956]: https://github.com/thoughtbot/shoulda-matchers/pulls/956
+[#870]: https://github.com/thoughtbot/shoulda-matchers/issues/870
+[#861]: https://github.com/thoughtbot/shoulda-matchers/issues/861
+[#954]: https://github.com/thoughtbot/shoulda-matchers/issues/954
+[#1074]: https://github.com/thoughtbot/shoulda-matchers/pulls/1074
+[#1075]: https://github.com/thoughtbot/shoulda-matchers/pulls/1075
+[#1077]: https://github.com/thoughtbot/shoulda-matchers/pulls/1077
+[#961]: https://github.com/thoughtbot/shoulda-matchers/issues/961
+[795ca68]: https://github.com/thoughtbot/shoulda-matchers/commit/795ca688bff08590dbd2ab6f2b51ea415e0c7473
+[#1089]: https://github.com/thoughtbot/shoulda-matchers/pulls/1089
+[#904]: https://github.com/thoughtbot/shoulda-matchers/issues/904
 
 ### Improvements
 
-* Update `BigDecimal.new()` to use `BigDecimal()` and avoid deprecation warnings
-  in Ruby 2.6.
+* Replace usage of Fixnum with Integer to prevent Ruby 2.4 from emitting
+  deprecation warnings.
+
+  * *Commits: [61c3654], [03a1d21]*
+  * *PRs: [#1040], [#1031], [#1009]*
+  * *Original issue: [#1001]*
+
+[61c3654]: https://github.com/thoughtbot/shoulda-matchers/commit/61c365416a09c5cffd7fcb774a07de4abf8e9afd
+[03a1d21]: https://github.com/thoughtbot/shoulda-matchers/commit/03a1d213805a44a0aec99857e01cab8524aa0c05
+[#1040]: https://github.com/thoughtbot/shoulda-matchers/pulls/1040
+[#1031]: https://github.com/thoughtbot/shoulda-matchers/pulls/1031
+[#1009]: https://github.com/thoughtbot/shoulda-matchers/pulls/1009
+[#1001]: https://github.com/thoughtbot/shoulda-matchers/issues/1001
 
 # 3.1.2
 
 ### Deprecations
 
-* This is the **last version** that supports Rails 4.0 and 4.1 and Ruby 2.0 and 2.1.
+* This is the **last version** that supports Rails 4.0 and 4.1 and Ruby 2.0 and
+  2.1.
 
 ### Bug fixes
 
@@ -23,6 +191,10 @@
   * *Issue: [#899]*
   * *Pull request: [#902]*
 
+[44c019]: https://github.com/thoughtbot/shoulda-matchers/commit/44c0198830921650af3b4a56f5d72aaae2168480
+[#899]: https://github.com/thoughtbot/shoulda-matchers/issues/899
+[#902]: https://github.com/thoughtbot/shoulda-matchers/pulls/902
+
 # 3.1.1
 
 ### Bug fixes