Discussion on the current meaning of `is_reserved` and `is_locked` in CiviCRM. Suggestions for improvements.

is_reserved_meaning.md

DAO Definitions

These definitions are from the docblock comment on the DAO properties. A quick search for public $is_reserved showed 10 entities with this property, but I will focus on these three for now.

Option Group

• is_reserved: Is this a predefined system option group (i.e. it can not be deleted)?
• is_locked: A lock to remove the ability to add new options via the UI.

Option Value

• is_reserved: Is this a predefined system object?

Custom Group

• is_reserved: Is this a reserved Custom Group?

In Reality

Type	Editable via UI	Editable via API
Reserved Custom Group	No, does not appear in civicrm/admin/custom/group	Yes, could delete
Locked Option Group	Yes**, but addding new options is disabled. Non-reserved option values can be deleted	Yes, could delete
Reserved Option Group	Yes**, options can be added and deleted	Yes, could delete
Reserved Option Value	Yes, but option to delete doesn't appear	Yes, could delete

** I can't find any way to delete any option group via the UI

Real Definitions

• is_reserved: For custom groups it means "hide it from editing in the UI". For option values it means "hide delete option in the UI". For option groups it means nothing.
• is_locked: For options groups it means "hide the option to add a new option value"

Goals

• As an extension developer I want to ensure some critical option groups and custom groups will not be deleted. I still want to be able to edit or delete them via the API (for example in hook_civicrm_uninstall).
• As an organization we want to have a consistent language with the same rules being applied each time a concept such as is_reserved is used.

Suggestions

• is_reserved means it will be uneditable from the UI. Attempts to modify via API will fail. Modification is possible, but only after changing is_reserved to false.
• is_locked is only for groups containing child items. It means no items can be added or removed.
• is_reserved is ignored on child items if the parent is deleted. For example, deleting a non-reserved option_group will also delete reserved option_values in it.

Problems

• While it would be simpler to say is_reserved means uneditable, there are some properties would be very helpful to edit, even if the entity was reserved. For example "Title" and "Descrption" for option_group, "Weight", "Description" and "Label" for option_value or "Title" and "Weight" for custom_group. We might consider allowing edits to just these properties for reserved entities. That said, it would be much easier to stick to the logic of disallowing any edit to reserved entities.
• There could be some confusion if we hide reserved items. We might decide to show reserved items, but in uneditable form.

@colemanw @totten I thought it was a funny coincidence that while we're discussing this issue someone in CiviHR made a PR to delete reserved relationship types, which would probably lead to a while world of trouble compucorp/civihr#2554