Group mutableCopy function should not return null even if readOnly is true in order to support usages by sync adapters

[vestrel00]

Problem

The Group.mutableCopy() function returns null if Group.readOnly is true. It was intentionally written this way to prevent applications from attempting to perform an update operation because it would fail if the group is read-only.

As a consequence, sync adapters are unable to use this API unless they bypass this limitation by using the following workaround,

val nonNullGroup = group.copy(readOnly = false).mutableCopy()!!

Here's the official documentation on ContactsContract.GroupsColumns.GROUP_IS_READ_ONLY,

Solution

The Group.mutableCopy() function should not return null even if it is read-only.

This may cause users of this library to attempt to update read-only groups, which will result in a failed operation. However, this behavior is actually more in-line with the rest of the API design so it should be okay.

• Check/update all usages of Group.mutableCopy().
• Change GroupsUpdate.groups function to only allow non-nullable groups and update function docs.
• Update all in-code documentation.
• Update docs, where necessary.
• Update gh-pages branch, if necessary.
• Provide migration guide.

Note

I am aware that the APIs in this library currently does not support setting CALLER_IS_SYNCADAPTER to true. This means that even with the resolution of this issue, users will still be unable to update/delete read-only groups even if they are building a sync adapter. Future support for setting CALLER_IS_SYNCADAPTER in library APIs IS coming in #308!

[vestrel00]

Migration guide (to be included in release notes)

PREVIOUSLY, the Group.mutableCopy() function may return null if the group is read-only.

NOW, it will no longer return null even if the group is read-only.

🗒️ Read the new documentation for the full guide!

[vestrel00]

🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥
This is now release in 0.3.1!
🔥 🔥 🔥 🔥 🔥 🔥 🔥 🔥