Update README & LICENSE; add CONTRIBUTING

[ci skip]

Author: mcmire

CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Want to make a change to this library?
+Great! Here's how you do that.
+
+First, create a fork of this repo,
+cloning it to your computer
+and running the following command in the resulting directory
+in order to install dependencies:
+
+```
+bin/setup
+```
+
+After this, you can run all of the tests
+to make sure everything is kosher:
+
+```
+bundle exec rake
+```
+
+Next, make changes to the code as necessary.
+Code is linted using Rubocop,
+so make sure that's set up in your editor.
+If you update one of the tests,
+you can run it like so:
+
+```
+bin/rspec spec/integration/...
+bin/rspec spec/unit/...
+```
+
+Finally, submit your PR.
+I'll try to respond as quickly as I can.
+I may have suggestions about code style or your approach,
+but hopefully everything looks good and your changes get merged!
+Now you're a contributor! 🎉

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2018 Elliot Winkler.
+Copyright (c) 2018-2020 Elliot Winkler.
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

README.md

@@ -7,32 +7,33 @@
 [hound-badge]: https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg
 [hound]: https://houndci.com
 
-SuperDiff is a gem that hooks into RSpec to intelligently display the
-differences between two data structures of any type.
+SuperDiff is a gem that hooks into RSpec
+to intelligently display the differences between two data structures of any type.
 
 📢 **[See what's changed in the latest version (0.4.0)][changelog].**
 
 [changelog]: CHANGELOG.md
 
 ## Introduction
 
-The primary motivation behind this gem is to vastly improve upon RSpec's
-built-in diffing capabilities.
+The primary motivation behind this gem
+is to vastly improve upon RSpec's built-in diffing capabilities.
 
-Sometimes, whenever you use a matcher such as `eq`, `match`, `include`, or
-`have_attributes`, you will get a diff of the two data structures you are trying
-to match against. This is great if all you want to do is compare multi-line
-strings. But if you want to compare other, more "real world" kinds of values —
-nested data structures (arrays, hashes, and full-scale objects), such as what
-you might work with when developing API endpoints or testing methods that make
-database calls and return a set of model objects — then you are out of luck.
-Since [RSpec merely runs your `expected` and `actual` values through Ruby's
-PrettyPrinter library][rspec-differ-fail] and then performs a diff of these
-strings, the output it produces leaves much to be desired.
+Sometimes, whenever you use a matcher such as `eq`, `match`, `include`, or `have_attributes`,
+you will get a diff of the two data structures you are trying to match against.
+This is great if all you want to do is compare multi-line strings.
+But if you want to compare other, more "real world" kinds of values,
+such as what you might work with when developing API endpoints
+or testing methods that make database calls and return a set of model objects,
+then you are out of luck.
+Since [RSpec merely runs your `expected` and `actual` values through Ruby's PrettyPrinter library][rspec-differ-fail]
+and then performs a diff of these strings,
+the output it produces leaves much to be desired.
 
 [rspec-differ-fail]: https://github.com/rspec/rspec-support/blob/c69a231d7369dd165ad7ce4742e1a2e21e3462b5/lib/rspec/support/differ.rb#L178
 
-For instance, let's say you wanted to compare these two hashes:
+For instance,
+let's say you wanted to compare these two hashes:
 
 ``` ruby
 actual = {
@@ -86,36 +87,60 @@ You would get output that looks like this:
 
 ![Before super_diff](doc/before.png)
 
-What this library does is to provide a diff engine that knows how to figure out
-the differences between any two data structures and display them in a sensible
-way. So, using the example above, you'd get this instead:
+What this library does
+is to provide a diff engine
+that knows how to figure out the differences between any two data structures
+and display them in a sensible way.
+So, using the example above,
+you'd get this instead:
 
 ![After super_diff](doc/after.png)
 
 ## Installation
 
-Want to try out this gem for yourself? As with most development-related gems,
-there are a couple ways depending on your type of project:
+There are a few different ways to install `super_diff`
+depending on your type of project.
 
 ### Rails apps
 
-If you're developing a Rails app, add the following to your Gemfile:
+If you're developing a Rails app,
+add the following to your Gemfile:
 
 ``` ruby
-gem "super_diff"
+group :test do
+  gem "super_diff"
+end
 ```
 
-After running `bundle install`, add the following to your `rails_helper`:
+After running `bundle install`,
+add the following to your `rails_helper`:
 
 ``` ruby
 require "super_diff/rspec-rails"
 ```
 
-You're done!
+### Projects using some part of Rails (e.g. ActiveModel)
 
-### Libraries
+If you're developing an app using Hanami or Sinatra,
+or merely using a part of Rails such as ActiveModel,
+add the following to your Gemfile where appropriate:
 
-If you're developing a library, add the following to your gemspec:
+``` ruby
+gem "super_diff"
+```
+
+After running `bundle install`,
+add the following to your `spec_helper`:
+
+``` ruby
+require "super_diff/rspec"
+require "super_diff/active_support"
+```
+
+### Gems
+
+If you're developing a gem,
+add the following to your gemspec:
 
 ``` ruby
 spec.add_development_dependency "super_diff"
@@ -127,14 +152,16 @@ Now add the following to your `spec_helper`:
 require "super_diff/rspec"
 ```
 
-You're done!
-
 ## Configuration
 
-As capable as this library is, it doesn't know how to deal with every kind of
-object out there. You might find it necessary to instruct the gem on how to diff
-your object. To do this, you can use a configuration block. Simply add this to
-your test helper file (`rails_helper` or `spec_helper`):
+As capable as this library is,
+it doesn't know how to deal with every kind of object out there.
+If you have a custom class,
+and instances of your class aren't appearing in diffs like you like,
+you might find it necessary to instruct the gem on how to handle them.
+In that case
+you would add something like this to your test helper file
+(`rails_helper` or `spec_helper`):
 
 ``` ruby
 SuperDiff::RSpec.configure do |config|
@@ -144,62 +171,53 @@ SuperDiff::RSpec.configure do |config|
 end
 ```
 
-*(More info here in the future on adding a custom differ, operational sequencer,
-and diff formatter. Also explanations on what these are.)*
+*(More info here in the future on adding a custom differ, operational sequencer, and diff formatter.
+Also explanations on what these are.)*
 
-## Contributing
-
-If you encounter a bug or have an idea for how this could be better, feel free
-to [create an issue](https://github.com/mcmire/super_diff/issues).
-
-If you'd like to submit a PR instead, here's how to get started. First, fork
-this repo. Then, when you've cloned your fork, run:
-
-```
-bin/setup
-```
+## Support
 
-This will install various dependencies. After this, you can run all of the
-tests:
+My goal for this library is to improve your development experience.
+If this is not the case,
+and you encounter a bug or have a suggestion,
+feel free to [create an issue][issues-list].
+I'll try to respond to it as soon as I can!
 
-```
-bundle exec rake
-```
-
-If you update one of the tests, you can run it like so:
+[issues-list]: https://github.com/mcmire/super_diff/issues
 
-```
-bin/rspec spec/integration/...
-bin/rspec spec/unit/...
-```
+## Contributing
 
-Finally, submit your PR and I'll take a look at it when I get a chance.
+Any contributions to improve this library are welcome!
+Please see the [contributing](./CONTRIBUTING.md) document for more on how to do that.
 
 ## Compatibility
 
-`super_diff` is [tested][travis] to work with Ruby >= 2.4.x, RSpec 3.x, and
-Rails >= 5.x.
+`super_diff` is [tested][travis] to work with
+Ruby >= 2.4.x,
+RSpec 3.x,
+and Rails >= 5.x.
 
 [travis]: http://travis-ci.org/mcmire/super_diff
 
 ## Inspiration/Thanks
 
-In developing this gem I made use of or was heavily inspired by these libraries:
+In developing this gem
+I made use of or was heavily inspired by these libraries:
 
-* [Diff::LCS][diff-lcs], the library I started with in the [original version of
-  this gem][original-version] (made in 2011!)
-* The pretty-printing algorithms and API within [PrettyPrinter][pretty-printer]
-  and [AwesomePrint][awesome-print], from which I borrowed ideas to develop
-  the [inspectors][inspection-tree].
+* [Diff::LCS][diff-lcs],
+  the library I started with in the [original version of this gem][original-version]
+  (made in 2011!)
+* The pretty-printing algorithms and API within [PrettyPrinter][pretty-printer] and [AwesomePrint][awesome-print],
+  from which I borrowed ideas to develop the [inspectors][inspection-tree].
 
-Thank you so much!
+Thank you to the authors of these libraries!
 
 [original-version]: https://github.com/mcmire/super_diff/tree/old-master
 [diff-lcs]: https://github.com/halostatue/diff-lcs
 [pretty-printer]: https://github.com/ruby/ruby/tree/master/lib/prettyprint.rb
 [awesome-print]: https://github.com/awesome-print/awesome_print
 [inspection-tree]: https://github.com/mcmire/super_diff/blob/master/lib/super_diff/object_inspection/inspection_tree.rb
 
-## Copyright/License
+## Author/License
 
-© 2018-2019 Elliot Winkler, released under the [MIT license](LICENSE).
+`super_diff` was created and is maintained by Elliot Winkler.
+It is released under the [MIT license](LICENSE).