Merge branch 'master' into prepare-1.4

# Conflicts:
#	docs/RELEASE_NOTES.md
#	docs/usage/CATEGORY_SYNC.md
#	docs/usage/INVENTORY_SYNC.md
#	docs/usage/PRODUCT_SYNC.md
#	docs/usage/PRODUCT_TYPE_SYNC.md

docs/RELEASE_NOTES.md

@@ -42,6 +42,14 @@
 [Javadoc](https://commercetools.github.io/commercetools-sync-java/v/1.4.0/) | 
 [Jar](https://bintray.com/commercetools/maven/commercetools-sync-java/1.4.0)
 
+
+- 🎉 **New Features** (5)
+    - **ProductType Sync** - Introduced support for syncing product types with NestedType (or set of NestedType) attributes in any order. [#372](https://github.com/commercetools/commercetools-sync-java/issues/372)
+    - **ProductType Sync** - Introduced the new `ProductTypeReferenceReplacementUtils#replaceProductTypesReferenceIdsWithKeys` which is a util that replaces the reference ids with keys in a list of productTypes. [#372](https://github.com/commercetools/commercetools-sync-java/issues/372)
+    - **ProductType Sync** - Introduced the new `ProductTypeReferenceReplacementUtils#buildProductTypeQuery` utils to create a product type query with all needed reference expansions to fetch productTypes from a source CTP project for the sync. [#372](https://github.com/commercetools/commercetools-sync-java/issues/372)
+    - **ProductType Sync** - Introduced the new `ProductTypeReferenceResolver` which resolves productType references on ProductTypeDrafts. [#372](https://github.com/commercetools/commercetools-sync-java/issues/372)
+    - **ProductType Sync** - Introduced the new methods `ProductTypeSyncStatistics#getNumberOfProductTypesWithMissingNestedProductTypes` and `ProductTypeSyncStatistics#getProductTypeKeysWithMissingParents` which represents the nested product types which are still not resolved. [#372](https://github.com/commercetools/commercetools-sync-java/issues/372)
+
 - 🛠️ **Enhancements** (8)
     - **Commons** - Bumped commercetools-jvm-sdk to version [1.45.0](http://commercetools.github.io/commercetools-jvm-sdk/apidocs/io/sphere/sdk/meta/ReleaseNotes.html#v1_45_0).
     - **Commons** - Bumped gradle to version [gradle-5.5.1](https://docs.gradle.org/5.5.1/release-notes.html)
@@ -59,11 +67,11 @@
 
 - 🎉 **New Features** (6)
     - **CartDiscount Sync** - Added support for syncing cart discounts. [#379](https://github.com/commercetools/commercetools-sync-java/issues/379) For more info how to use it please refer to [CartDiscount usage doc](/docs/usage/CART_DISCOUNT_SYNC.md).
-    - **CartDiscount Sync** - Exposed `CartDiscountSyncUtils#buildActions` which calculates all needed update actions after comparing a `CartDiscount` and a `CartDiscountDraft`. [[#379](https://github.com/commercetools/commercetools-sync-java/issues/379)
-    - **CartDiscount Sync** - Exposed `CartDiscountUpdateActionUtils` which contains utils for calculating needed update actions after comparing individual fields of a `CartDiscount` and a `CartDiscountDraft`. [#379](https://github.com/commercetools/commercetools-sync-java/issues/379)
+    - **CartDiscount Sync** - Introduced the new `CartDiscountSyncUtils#buildActions` which calculates all needed update actions after comparing a `CartDiscount` and a `CartDiscountDraft`. [#379](https://github.com/commercetools/commercetools-sync-java/issues/379)
+    - **CartDiscount Sync** - Introduced the new `CartDiscountUpdateActionUtils` which contains utils for calculating needed update actions after comparing individual fields of a `CartDiscount` and a `CartDiscountDraft`. [#379](https://github.com/commercetools/commercetools-sync-java/issues/379)
     - **CartDiscount Sync** - Introduced the new `CartDiscountReferenceResolver` which resolves custom type references on CartDiscountDrafts. [#379](https://github.com/commercetools/commercetools-sync-java/issues/379)
-    - **CartDiscount Sync** - Introduced new `CartDiscountReferenceReplacementUtils#replaceCartDiscountsReferenceIdsWithKeys` which is a util that replaces the custom type ids with keys in a list of cartDiscounts. [#379](https://github.com/commercetools/commercetools-sync-java/issues/379)
-    - **CartDiscount Sync** - Exposed `CartDiscountReferenceReplacementUtils#buildCartDiscountQuery` util to create a cart discount query with all needed reference expansions to fetch cart discounts from a source CTP project for the sync. [#379](https://github.com/commercetools/commercetools-sync-java/issues/379).
+    - **CartDiscount Sync** - Introduced the new `CartDiscountReferenceReplacementUtils#replaceCartDiscountsReferenceIdsWithKeys` which is a util that replaces the custom type ids with keys in a list of cartDiscounts. [#379](https://github.com/commercetools/commercetools-sync-java/issues/379)
+    - **CartDiscount Sync** - Introduced the new `CartDiscountReferenceReplacementUtils#buildCartDiscountQuery` util to create a cart discount query with all needed reference expansions to fetch cart discounts from a source CTP project for the sync. [#379](https://github.com/commercetools/commercetools-sync-java/issues/379).
 
 - 🐞 **Bug Fixes** (1)
     - **Commons** -  Fixed a bug in the `BaseSyncStatistics` which caused a wrong calculation of the `latestBatchProcessingTimeInMinutes`. [#378](https://github.com/commercetools/commercetools-sync-java/issues/378)
@@ -83,7 +91,7 @@
 
 - 🚧 **Breaking Changes** (2)
     - **ProductType Sync** - Removed the unneeded `AttributeDefinitionCustomBuilder` which was an exposed but internal helper. [#377](https://github.com/commercetools/commercetools-sync-java/issues/377). 
-    - **Commons** - `SyncUtils#replaceReferenceIdWithKey` now renamed to `SyncUtils#getReferenceWithKeyReplaced`. [#394](https://github.com/commercetools/commercetools-sync-java/issues/394)
+    - **Commons** - `SyncUtils#replaceReferenceIdWithKey` is now renamed to `SyncUtils#getReferenceWithKeyReplaced`. [#394](https://github.com/commercetools/commercetools-sync-java/issues/394)
 
 - 🎉 **New Features** (2)
     - **Commons** - Added the new `CommonTypeUpdateActionUtils#buildUpdateActionForReferences` which is used for comapring references/resourceIdentifiers and buiding an update action if needed. [#394](https://github.com/commercetools/commercetools-sync-java/issues/394)

docs/usage/CATEGORY_SYNC.md

@@ -36,7 +36,7 @@ otherwise they won't be matched.
     - Provide the `key` value on the `id` field of the reference. This means that calling `getId()` on the
     reference would return its `key`.  
 
-   **Note**: This library provides you with a utility method 
+   **Note**: When syncing from a source commercetools project, you can use this util which this library provides: 
     [`replaceCategoriesReferenceIdsWithKeys`](https://commercetools.github.io/commercetools-sync-java/v/1.4.0/com/commercetools/sync/categories/utils/CategoryReferenceReplacementUtils.html#replaceCategoriesReferenceIdsWithKeys-java.util.List-)
     that replaces the references id fields with keys, in order to make them ready for reference resolution by the sync:
     ````java

docs/usage/INVENTORY_SYNC.md

@@ -34,7 +34,7 @@ against a [InventoryEntryDraft](https://docs.commercetools.com/http-api-projects
    - Provide the `key` value on the `id` field of the reference. This means that calling `getId()` on the
    reference would return its `key`. 
 
-        **Note**: This library provides you with a utility method 
+        **Note**: When syncing from a source commercetools project, you can use this util which this library provides: 
          [`replaceInventoriesReferenceIdsWithKeys`](https://commercetools.github.io/commercetools-sync-java/v/1.4.0/com/commercetools/sync/inventories/utils/InventoryReferenceReplacementUtils.html#replaceInventoriesReferenceIdsWithKeys-java.util.List-)
          that replaces the references id fields with keys, in order to make them ready for reference resolution by the sync:
          ````java

docs/usage/PRODUCT_SYNC.md

@@ -39,7 +39,7 @@ order for the sync to resolve the actual ids of those references, those `key`s h
     - Provide the `key` value on the `id` field of the reference. This means that calling `getId()` on the
     reference would return its `key`. 
 
-        **Note**: This library provides you with a utility method 
+        **Note**: When syncing from a source commercetools project, you can use this util which this library provides: 
          [`replaceProductsReferenceIdsWithKeys`](https://commercetools.github.io/commercetools-sync-java/v/1.4.0/com/commercetools/sync/products/utils/ProductReferenceReplacementUtils.html#replaceProductsReferenceIdsWithKeys-java.util.List-)
          that replaces the references id fields with keys, in order to make them ready for reference resolution by the sync:
          ````java

docs/usage/PRODUCT_TYPE_SYNC.md

@@ -32,9 +32,23 @@ against a [ProductTypeDraft](https://docs.commercetools.com/http-api-projects-pr
 product types in the target CTP project. Also, the product types in the target project are expected to have the `key`
 fields set, otherwise they won't be matched.
 
-2. Create a `sphereClient` [as described here](IMPORTANT_USAGE_TIPS.md#sphereclient-creation).
-
-3. After the `sphereClient` is setup, a `ProductTypeSyncOptions` should be be built as follows:
+2. Every productType may have `product type` references if it contains attributeDrafts of type `NestedType`. These 
+referenced are matched by their `key`s. Therefore, in order for the sync to resolve the actual ids of those 
+references, those `key`s have to be supplied in the following way:
+    - Provide the `key` value on the `id` field of the reference. This means that calling `getId()` on the
+    reference would return its `key`. 
+
+        **Note**: When syncing from a source commercetools project, you can use this util which this library provides: 
+         [`replaceProductTypesReferenceIdsWithKeys`](https://commercetools.github.io/commercetools-sync-java/v/1.4.0/com/commercetools/sync/producttypes/utils/ProductTypeReferenceReplacementUtils.html#replaceProductTypesReferenceIdsWithKeys-java.util.List-)
+         that replaces the references id fields with keys, in order to make them ready for reference resolution by the sync:
+         ````java
+         // Puts the keys in the reference id fields to prepare for reference resolution
+         final List<ProductTypeDraft> productTypeDrafts = replaceProductTypesReferenceIdsWithKeys(productTypes);
+         ````
+
+3. Create a `sphereClient` [as described here](IMPORTANT_USAGE_TIPS.md#sphereclient-creation).
+
+4. After the `sphereClient` is setup, a `ProductTypeSyncOptions` should be be built as follows:
 ````java
 // instantiating a ProductTypeSyncOptions
 final ProductTypeSyncOptions productTypeSyncOptions = ProductTypeSyncOptionsBuilder.of(sphereClient).build();
@@ -99,5 +113,5 @@ More examples of those utils for different fields can be found [here](https://gi
 
 
 ## Caveats    
-1. Syncing product types with an attribute of type [NestedType](https://docs.commercetools.com/http-api-projects-productTypes.html#nestedtype) is not supported yet.
-1. Syncing product types with an attribute of type `Set` of `NestedType` attribute is supported. However, `Set` of (`Set` of `Set` of..) of `NestedType` is not yet supported.
+1. The order of attribute definitions in the synced product types is not guaranteed.
+2. Syncing product types with an attribute of type `Set` of `NestedType` attribute is supported. However, `Set` of (`Set` of `Set` of..) of `NestedType` is not yet supported.