UX Bug: Use of Custom Groups in Protected Branches is too hard to discover naturally

Summary

The UX for selecting "Roles, Users and Groups" when setting "Protected Branches" does not give sufficient hints as to the existence of the capability to use custom groups rather than only Roles or Users.

This is made worse by the fact that:

  • the documentation also does not give note to this capability ( Addressed in #37338 (closed) )
  • there is a prerequisite setup step for any UI to appear - making the capability discoverable (overly context sensitive)
  • Custom group capabilities in Protected Branches is a critical feature point for pre-sales customers who are evaluating the product for it's Role Based Access Controls (RBAC) for controlling both 1) code changes and 2) deployments to environments including production. If they cannot discover the capability without consulting GitLab as a company they are likely to assume it does not exist via the human bias to WYSIATI (What You See Is All There Is).

Steps to reproduce

  1. While in a state of imaging you are trying to discover the full RBAC capabilities of GitLab for the first time...
  2. Open "Branch Protections" on a repository and play with the controls to...
  3. Examine it for clues that you can use custom groups.
  4. Consult the documentation (as of 11/26/2019) to understand whether and how groups can be configured.
  5. Optional: Attempt the same configuration in Merge Approval Rules (note that the group selector is always present - but this is considered a bug and is slated to be fixed - but it is much more discoverable)
  6. In the repo you have been working on, add a custom group to the repo as a "Maintainer" in the repo "Members" page
  7. Revisit "Branch Protections" and in the selector notice a new heading "Groups" and the one group you added to the repository.

What is the current bug behavior?

The discovery of critical functionality by new users and product reviewers (and paid customers) is degraded. Documentation should also be amended - but in-product discoverability is always much more effective due to the WYSIATI effect.

What is the expected correct behavior?

New users (especially product reviewers) should be given more inituitive queues as to "what is possible" in this configuration panel even when the technical prerequisites to expose that functionality are not present.

For instance, always displaying "Groups" in this selector and then, if requirements aren't met a note stating what needs to be done - such as "Groups that are added in this projects Members page will appear here."

Relevant logs and/or screenshots

Protected Branches: No group indicator if group not already added in "members"

Try at: https://gitlab.com/dsanoy-demo/test/protected-branches-custom-groups/protected-branches-no-group/-/settings/repository

ProtectedBranchesNoGroupIndicator

Protected Branches: Groups capability indication only if at least one group is already added in "members"

Try at: https://gitlab.com/dsanoy-demo/test/protected-branches-custom-groups/protected-branches-with-group/-/settings/repository

ProtectedBranchesNoGroupIndicator

By contracts Merge Approval Rules show regardless of groups added to "Members" area:

Try at: https://gitlab.com/dsanoy-demo/test/protected-branches-custom-groups/protected-branches-no-group/-/settings/repository

MergeApprovalRulesAlwaysShowGroups

Output of checks

This bug happens on GitLab.com

Possible fixes

Always displaying "Groups" in this selector and then, if requirements aren't met a note stating what needs to be done - such as "Groups that are added in this projects Members page will appear here."

Other links/references

#37338 (closed) - Docs bug: "Protected Branches" Docs Does Not Sufficiently Cover The Ability to Use Custom Groups

#2048 (comment 250600537) - commented on issue to avoid this problem in both UX and documentation from the start if Merge Approval Rules are updated to act like Protected Branches (require groups be added to Members before being used)

Edited by DarwinJS