provide more details on source build process

src/partners/sources.md

@@ -22,7 +22,74 @@ Before you begin, you need access to the Developer Portal. To access the Develop
 
 4. Select the **Catalog info** tab and add relevant metadata and catalog information for your source.
 
-The code for your source should follow the format of Segment's [HTTP API](/docs/connections/sources/catalog/libraries/server/http-api/).
+## Understanding the integration
+
+To complete the source set up flow, the customer will need to input the Segment write key for this source in your integrations settings UI. This will enable your tool to route customer data back to Segment correctly. 
+
+To send events to Segment you should post events directly to the [Segment HTTP API](/docs/connections/sources/catalog/libraries/server/http-api/#track). You may use any server-side Segment [library](/docs/connections/sources/catalog/) to do so.
+
+## The Segment Spec
+
+Building your source will require defining the event data that you send to Segment. Segment's spec is a critical component of preserving semantics between sources and destinations. 
+
+If you break the spec, you are breaking the promise of Segment, which is grounds for removal from the catalog. To learn about the semantics of the five supported API calls, and the semantic event names and properties Segment recognizes, read the [Segment Spec](/docs/connections/spec).
+
+Within the Spec, there are a few requirements for partner Streams worth pointing out. 
+
+### `userId`
+
+Each call sent to Segment must contain a  `userId`. The `userId` is what allows Segment to identify each unique user. This value should be stored by your tool when you receive an event from Segment.
+
+For example, you might receive an `identify` call with a `userId` and `traits` about that user. If that user is sent an email and opens that email, you would want to send an `Email Opened` event back to Segment with that same `userId` . The `userId` should be part of the call body as a top-level object.
+
+> info ""
+>  For Customers, it's critical that the `userId` be consistent across all data flowing through Segment — this has significant implications for Segment billing (based on unique Monthly Tracked Users) and usefulness of data in integrations/warehouses. Passing back the `userId` value sent from Segment into your tool should be the default behavior of your track calls. If you're not a destination, make sure that you're using the customer's internal database ID, not your tool's ID.
+
+If you have your own unique identifier you use in your tool, Segment recommends passing that along as a context property in the event for QA purposes. For example:
+
+```json
+    "type": "track",
+    "userId": "abc",
+    "traits": {
+        "email": "customer@company.com"
+     }
+     "context": {
+       "yourToolId": "123"
+     },
+```
+
+### `integration`
+
+Each call should contain a `context.integration` object in the call body that identifies your tool (for example where the call is coming from). Use the slugified name for your tool, and `1.0.0` as the initial version — if you're unsure of your integration slug, contact Segment support. Once Streams are supported in the Developer Center, this will be rendered for you and will be validated as part of the QA process.
+
+This should be part of the `context` top-level object and will look like:
+
+```json
+    "context": {
+      "integration": {
+        "name": "your-tool",
+        "version": "1.0.0"
+      }
+    }
+```
+
+### `writeKey`
+
+Each call must contain a `writeKey`. Segment provides this `writeKey` to customers in the settings panel for each of their sources. As mentioned in the set up flow description above, customers will need to save their Segment write key in your UI in order authenticate calls being made by your tool.
+
+The write key is required in the header of every call to identify the customer whose data Segment receives. See the [authentication section](/docs/connections/sources/catalog/libraries/server/http-api/#authentication) of the HTTP API docs for more detail. If you do not include a customer write key in the call header, Segment will reject track calls from your tool.
+
+**Rate limits and batching**
+There is no hard rate limit at which point Segment will drop your data. However, to avoid processing delays, Segment asks partners to send requests at a maximum rate of 50 requests per second.
+
+If you want to batch requests to the HTTP endpoint, refer to the batching documentation [here](/docs/connections/sources/catalog/libraries/server/http-api/#import). The suggested maximum rate includes any batch requests.
+
+## Regional Segment
+
+Segment offers customers the option to lead on data residency by providing [regional infrastructure](/docs/guides/regional-segment) in both the Europe and the United States. In order for your source to be available in an EU workspace, you will need to provide the ability for the Segment user to post their data to the EU ingestion endpoint: 
+
+- Oregon (US Default) — `api.segment.io/v1`
+- Dublin — `events.eu1.segmentapis.com/`
 
 ## Test your Source