README.md in quiz_api_client-2.4.0 vs README.md in quiz_api_client-2.4.1

@@ -177,5 +177,55 @@
 Then, run `rake spec` to run the tests.
 
 You can also run `rake console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+When you add or modify a service, be sure to add or modify contract tests!
+
+## Contract Tests
+
+We use [Pact](https://docs.pact.io/) for our contract testing. To generate
+a Pact file, run `bin/contracts`.
+
+The `bin/contracts` script will generate the Pact file and place it in the
+pacts/ directory. It will also attempt to publish the Pact file to a local
+Pact Broker.
+
+### Development Workflow:
+
+1. In the quiz_api repo, spin up the Quiz API service with `bin/dev-setup`
+2. In the quiz_pact_broker repo, spin up a Pact Broker with `bin/dev-setup`
+3. In the quiz_api repo, write Pact provider states in the
+spec/service_consumers/quiz_api_client_ruby/ directory as needed
+4. In this repo's spec/contracts/ directory, write or modify a contract test
+5. In this repo, run `bin/contracts` to generate a Pact file and publish it to
+the Pact Broker
+6. In the quiz_api repo, run `bin/contracts` to pull the new Pact file from
+the Pact Broker and run the updated contract tests against the Quiz API service
+
+Bonus: You can view your Pact file in the Pact Broker at http://pact-broker.docker
+along with some cool goodies!
+
+### Debugging Failures
+
+Pact has some basic RSpec output for failed specs. It also keeps a log in
+`log/pact.log` and offers general pointers for debugging.
+
+Above all, learn the Pact [basics](https://docs.pact.io/documentation/matching.html).
+
+### What should contract tests cover?
+
+The aim of contract testing here is *not* to test all functional requirements
+of the Quiz API service. Rather, the goal is to ensure changes to the Quiz API
+service don't break its clients. We can best accomplish this with the
+following contract test coverage:
+
+- Basic happy path requests for all endpoints (POST, GET, PUT, DELETE)
+- Basic error paths for all endpoints (verify the error messages and/or HTTP
+response codes are accurate)
+- Resource state management; for example, when a quiz attempt is submitted but
+not yet graded
+- Special edge case errors
+
+Again, what *not* to test: the functional behavior of the service; for
+example, a series of sequential API calls to test a full user scenario.