DEVELOPER_DOCUMENTATION.md in pact_broker-2.34.0 vs DEVELOPER_DOCUMENTATION.md in pact_broker-2.35.0

@@ -6,11 +6,13 @@
   * List of API endpoints - [lib/pact_broker/api.rb](lib/pact_broker/api.rb)
   * API - [lib/pact_broker/api](lib/pact_broker/api)
     * HTTP Resources - [lib/pact_broker/api/resources](lib/pact_broker/api/resources) These handle the HTTP requests.
     * Decorators - [lib/pact_broker/api/decorators](lib/pact_broker/api/decorators) These render the response bodies.
     * Contracts - [lib/pact_broker/api/contracts](lib/pact_broker/api/contracts) These validate incoming API requests.
-  * Domain - Domain classes were intially created in [lib/pact_broker/domain](lib/pact_broker/domain) but are now put in their own modules. The ones left here just haven't been migrated yet.
+  * Domain - Domain classes were intially created in [lib/pact_broker/domain](lib/pact_broker/domain) but are now put in their own modules. The ones left here just haven't been migrated yet. The module name is the plural of the domain class name. eg `lib/pact_broker/widgets/widget.rb`.
+  * Services and Repositories - in the module with the name of their domain concept. eg `lib/pact_broker/widgets/service.rb` and `lib/pact_broker/widgets/repository.rb`
+  * Standalone "function as class" classes go into the module they relate to. This pattern is used when there is some significant stateless logic that we want to
 * Database migrations - [db/migrations](db/migrations)
 
 * Tests - `spec`
   * Isolated tests (mostly) - `spec/lib`
   * Contract tests - `spec/service_consumers`
@@ -93,5 +95,26 @@
 
 ### Useful to know stuff
 
 * The supported database types are Postgres (recommended), MySQL (sigh) and Sqlite (just for testing, not recommended for production). Check the travis.yml file for the supported database versions.
 * Any migration that uses the "order" column has to be defined using the Sequel DSL rather than pure SQL, because the word "order" is a key word, and it has to be escaped correctly and differently on each database (Postgres, MySQL, Sqlite).
+
+## Adding a resource
+
+* In `spec/features` add a new high level spec that executes the endpoint you're going to write. Don't worry if you're not sure exactly what it's going to look like yet - you can come back and change it as you go. Have a look at the other specs in the directory for the type of assertions that should be made. Basic rule of thumb is to check the http status code, and do a light touch of assertions on the body.
+* Create a new directory for the classes that relate to your new resource. eg For a "Foo" resource, create `lib/pact_broker/foos`
+* Create a new migration in `db/migrations` that creates the underlying database table.
+* Create a new database model for the resource that extends from Sequel::Model. eg `lib/pact_broker/foos/foo.rb`
+* Create a decorator in `spec/lib/pact_broker/api/decorators/` that will map to and from the representation that will be used in the HTTP request and response.
+  * Write a spec for the decorator.
+* You may need to create a contract to validate the request. This is kind of broken while I upgrade to the latest dry-validation library. See Beth for more details.
+* Add the HTTP resource in `lib/pact_broker/api/resources/`. It should extend from `BaseResource`.
+  * Write a spec for the resource, stubbing out the behaviour you expect from your service.
+* Add the route to `lib/pact_broker/api.rb`
+* Create a service that has the methods that you need for the resource. eg. `lib/pact_broker/foos/service.rb`
+  * Add the new service to `lib/pact_broker/services.rb`
+  * Write a spec for the service, stubbing out the behaviour you expect from your repository.
+* Create a repository eg. `lib/pact_broker/foos/repository.rb`.
+  * Add the new repository to `lib/pact_broker/repositories.rb`.
+  * Write a spec for the repository.
+* Go back and make the original feature spec pass.
+* Profit.