User group: add description to user group (closes #14986)

[NguyenThuyLan]

Description

This pull request introduces a new description field for user groups. The purpose of this update is to provide additional context and clarity about each group's purpose and usage within the system.

Key Changes

• Add optional description field to user group models
• Created a migration to add the new field to the database table
• Expose and update user group description in management API
• Update related tests to verify persistence and retrieval of description
• Display description in User group details and in list user groups when choosing user group for user
• Create and update description from backoffice

Why this change
#14986

After change

[bjarnef]

Maybe the icon should be aligned at top close to user group name, when some user group may have no description, others longer description and some one or many sections selected.

[AndyButland]

Looks great @LanThuyNguyen, nice to see a "full-stack" feature as one contribution! I had a few code comments which I've left inline. Please could you have a look at addressing them, and then tomorrow I'll pull it down for some testing.

[NguyenThuyLan]

Thank you @AndyButland , I updated my PR I also updated the user group Icon so to make it consistent with the Document type

[AndyButland]

I found an issue with the migration logic (likely after you refactored it following my first comment), which I've pushed a fix for.

Otherwise it all looks to work nicely.

There's small small styling alignment issues around the header where you edit the name, icon and description.

If you look at the document type one you'll see:

• The icon border only appears when you hover over it.
• The icon border aligns nicely with the top and bottom of the name and description text boxes

That's not the case for the user group header:

I think it might be nice to add the description to the collection view of user groups. Seems like there's room without it getting two cluttered. Perhaps best to truncate the input though so if it's more than a couple of lines long it gets truncated with an ellipsis (...).

[NguyenThuyLan]

Thanks @AndyButland , I have just updated as images below

[AndyButland]

The description in the collection looks good @LanThuyNguyen, and nice how you have presented the whole description in the hover text if it's truncated.

I still see the visual discrepancy between the document type and user group header though. For the document type, if you hover over the icon you can see the border aligns nicely with the top of the name field. For the user group, it doesn't. Looks to me that there's more padding between the top bar and the name field for the document type than we have for the user group.

User group:

Document type:

[NguyenThuyLan]

@AndyButland , Yes, I updated it. I was too focused on the icon 😁

[AndyButland]

@ronaldbarendse @KevinJump - you may need a heads-up about this. We are looking to add a description to user groups. I don't recall that Deploy supports user group schema deployments, and not sure about uSync, but in case either does or you have it in mind, please be aware of this PR.

[AndyButland]

All looks good to me from a back-end and testing perspective @LanThuyNguyen, great work.

@iOvergaard or @leekelleher - to me it's all fine on the front-end too, but maybe one of you could have a quick look-over from that perspective too please?

@NguyenThuyLan - to finish off, it would be worth reviewing the documentation on user groups please, and see if you can see any places where we should update text or screenshots to include reference to this new description field. If so, please create a PR for the docs with it marked as ready for release with the 17.1-rc (23/12/2025).

@nhudinh0309 - maybe you could look too here please, to see if we should update any E2E tests to verify we can create and update user groups with description fields.

[madsrasmussen]

It looks really good. A few details I think we should look into before merging:

• I think we should add descriptions for all the User Groups we ship out of the box. I wouldn’t expect each project to have to add these. If they are not happy with what we provide out of the box, they are free to overwrite them.

• One of the purposes of getting these descriptions was to clean up the bloated User Group Picker UI. When we have the descriptions in place for the built-in user groups, I think we should make a conditional in the user group ref element to only show the permission data when there is no description.

I have pushed the target of this PR to 17.2.

[NguyenThuyLan]

Hello, I've updated this PR as requested. Please review it again. I've also added a default description in DatabaseDataCreator. Let me know if you think this default description isn't suitable. @AndyButland @madsrasmussen

[AndyButland]

I think they are pretty good @NguyenThuyLan - I just tweaked a little and came up with the following, just looking to be a little more precise but still succinct:

Administrator
Users with full access to all sections and functionality

Writers
Users with permission to create and update but not publish content

Editors
Users with full permission to create, update and publish content

Translators
Users with permission to manage dictionary entries

Sensitive data
Users with the specific permission to be able to manage properties and data marked as sensitive

Just to note what we discussed outside of this chat on the PR - we could also include these in a migration, so migrated sites get these descriptions too. But it's also possible that someone has amended the definitions of these groups in an existing site, so it perhaps safer to not do this.

[AndyButland]

Just updating with how the user group picker now looks, which is is per the discussion above:

[bjarnef]

@AndyButland I have upgraded a site locally to 17.2.0, but I don't see this.

Migration state is this {A7B8C9D0-E1F2-4A5B-8C7D-9E0F1A2B3C4D}:

Umbraco-CMS/src/Umbraco.Infrastructure/Migrations/Upgrade/UmbracoPlan.cs

Line 152 in bb56752

To<V_17_2_0.AddDocumentUrlAlias>("{A7B8C9D0-E1F2-4A5B-8C7D-9E0F1A2B3C4D}");

Description column is added to umbracoUserGroup column:

but I don't see the description field in UI - am I missing something?

[AndyButland]

You seem to be missing the client-side updates. Something cached maybe? I see it as expected with a clean 17.2 install.

[bjarnef]

I thought, but opening in incognito mode shows the same.
Tried hard refresh and different browser too 😅

[iOvergaard]

I also see it on my upgraded database:

[bjarnef]

Nvm .. forgot update of Umbraco.Cms in UmbracoProject itself 🤦‍♂️

<PackageReference Include="Umbraco.Cms" Version="17.2.0" />

The migration ran because dependency in other projects were updated.

The description field is shown now.

It may be better to have margin-top: 1px instead of margin-top: -1px to not cover bottom of focus outline: