Update ReadMe with seeding and migrating entries docs

README.md

@@ -23,6 +23,7 @@ Doing this by hand through contentful's content model editor is a dangerous and
 
 Easiest way to get an idea of how to use this is an example!
 
+#### Migrating Models (Content Types)
 ```js
 const Migrations = require('contentful-migrations')
 
@@ -35,7 +36,11 @@ const migration = new Migrations({
 migration.migrateContentTypes().then(console.log)
 ```
 
-The `id` and `token` are your contentful space id and management token, respectively. The `models` param is a path to a folder that contains one or more model definitions. The model definitions are not super well documented by contentful. First, again, an example of a model file:
+The `id` and `token` are your contentful space id and management token, respectively. The `models` param is a path to a folder that contains one or more model definitions. 
+
+The model definitions are not super well documented by contentful. These fields were reverse-engineered out of the API response for when you manually create the content type model from their interface then fetch it via API. Better docs would be great from contentful, or from a friendly contributor who would be interested in adding them to this readme. In general, what you see above will cover most use cases for a content type though.
+
+First, again, an example of a model file (_Note: The model's `id` property, will be `undefined` in Contentful if not provided during migration_):
 
 ```js
 module.exports = {
@@ -99,10 +104,102 @@ module.exports = {
 
 This looks complex, but really just describes all the things you set up in your content model. The name, id, and type of your fields, as well as whether they are required, any validations, and field appearance if there is one.
 
-These fields were reverse-engineered out of the API response for when you manually create the content model from their interface then fetch it via API. Better docs would be great from contentful, or from a friendly contributor who would be interested in adding them to this readme. In general, what you see above will cover most use cases though.
-
 So, basically you make a folder full of the js model definitions, then just pass the path to that folder and run the migration library, and it will make the magic happen. You can pass a different environment's id depending on where you want it to update.
 
+#### Seeding/Migrating Entries (for Content Types)
+Migrating (or seeding) entries works much like migrating content types. 
+First, you set up the migration client making sure to provide a path to a folder of `entries`.
+
+```js
+const Migrations = require('contentful-migrations')
+
+const migration = new Migrations({
+  id: 'xxx',
+  token: 'xxx',
+  entries: 'path/to/entries/folder',
+  models: 'path/to/models/folder' // both paths can be defined from the start
+})
+
+// Or you can set the `models` or `entries` path after instantiating the client
+migration.setModelsPath('different/path/to/models')
+migration.setEntriesPath('different/path/to/entries')
+
+// Create entries from folder in the configured space, using the supplied `id` // if provided, or letting Contentful generate one if not.
+migration.seedEntries().then(console.log)
+
+// Update entries from folder in the configured space
+migration.migrateEntries().then(console.log)
+```
+
+An entry file simply needs a unique `id`, a `contentTypeId`, and a `fields` object containing the desired values for each field defined on the entry's content type model. This is more clearly demonstrated below with an example of an entry file (using the `Author` model above):
+
+(_Note: You may choose to use Contentful's Entry object as a guide and leave its `sys` metadata in place and/or pull the desired values from there. `contentful-migration`'s create and update functions will use the `id` in `sys` over the top level `id` if available._)
+
+```js
+module.exports = {
+  "id": "author1", // *required* for updating (migrating)
+  "contentTypeId": "author", // *required* for seeding
+  /** optional, but takes precedence over above keys if provided
+  "sys": { 
+    "id": "author1",
+    "contentType": { // content type meta data, per contentful docs
+      "sys": {
+        "type": "Link",
+        "linkType": "ContentType",
+        "id": "author"
+      }
+    }
+  },
+  */
+  "fields": {
+    "name": {
+      "en-US": "Carrot Creative"
+    },
+    "slug": {
+      "en-US": "carrot-creative"
+    },
+    "bio": {
+      "en-US": "A full-service digital agency"
+    },
+    "socialMedia": {
+      "en-US": [ // Array of linked Entries' metadata in "sys"
+        {
+          "sys": {
+            "type": "Link",
+            "linkType": "Entry",
+            "id": "socialMediaEntry1"
+          }
+        },
+        {
+          "sys": {
+            "type": "Link",
+            "linkType": "Entry",
+            "id": "socialMediaEntry2"
+          }
+        }
+      ]
+    },
+    "image": {
+      "en-US": { // Object of Image Asset's metadata in "sys"
+        "sys": {
+          "type": "Link",
+          "linkType": "Asset",
+          "id": "image1"
+        }
+      }
+    }
+  }
+}
+```
+
+## Difference between Seeding and Migrating Entries
+You may encounter issues if you attempt to **update** an entry in a space with an `id` that doesn't exist or if you attempt to **create** an entry without a `contentTypeId`. In short:
+
+**Seeding:** you may omit the `id` if you want Contentful to generate an `id` for the entry itself, which you'll have to retrieve manually if you intend to migrate (or update) using this package in the future. **You must** provide a `contentTypeId` when creating the Entry in either case.
+
+**Migrating:** you may omit the `contentTypeId` but **you must** provide an `id` for a proper update of the existing entry in Contentful.
+
+
 ### License & Contributing
 
 - Details on the license [can be found here](LICENSE.md)