Update APIs include function overhaul

[vestrel00]

Problem

Not including all fields in the include function of the Update, ProfileUpdate, and DataUpdate APIs could lead to unwanted and unexpected behavior.

Included fields result in expected behavior of updating the database to match the data contained in the ContactEntity/RawContactEntity instances.

On the other hand, fields that are not included result in a bit of unclear behavior that is not very well-documented. For example,

contactsApi.update().include(Fields.Email.all).rawContacts(rawContactToUpdate).commit()

Currently, the above will perform insert/update/delete database operations ensure that the emails in the Data table matches the emails contained in rawContactToUpdate.

All other data corresponding to non-included fields will be set to null or deleted if they are empty. This may have been the original desired behavior at the time of implementing include for update APIs. However, in retrospect, that is NOT how it should be. Users of this library can just set the data/properties in rawContactToUpdate to null if they want to remove it from the Data table...

Solution

Overhaul the behavior of the include functions in Update, ProfileUpdate, and DataUpdate such that;

1. Update operations are performed on data corresponding to included fields such that the Contacts Provider database tables contain the same data as the in-memory models provided in the operation.
   • This is already the current behavior.
2. Update operations are NOT performed on data corresponding to excluded/non-included fields such that the Contacts Provider database tables contain the same data before and after the operation. This may result in the database containing data that is different from the in-memory models provided in the operation.
   • This is NOT the current behavior. This is what needs to be done for this issue.

Note that "update operations" may involve insert/update/delete database operations internally.

Acceptance criteria

• Implement the solution
• Update all documentation in Kotlin files
• Update all documentation in markdown files
• Update gh-pages

[vestrel00]

This is included in release 0.2.1!