Group description field

[mdewhirst]

Code of Conduct

• I agree to follow Django's Code of Conduct

Feature Description

In the contrib.auth.group model I'd like to see a text field, group.description, between group.name and group.permissions. In the Admin it would appear immediately beneath the group name.

Problem

Groups, are also roles. Different roles demand different sets of permissions. IMHO, individual permissions are bad corporate security policy. Some roles can be sufficiently complex that there should be some way of documenting the requirements so that administrators and managers can understand which roles should be assigned to which users.

A simple text field 'Description' would potentially solve that problem.

Request or proposal

proposal

Additional Details

As a recent example, although unrelated to permissions on this occasion, I offered one of my customers the unofficial role of "Product owner" in return for a subscription discount. I will now use a group called "owner" so I can automate the offered discount. Without a description field documenting the intent of that group the next person in my position won't have a clue what that group is about.

BTW, here are all the group names in the above project ... admin, agent, author, authority, consultant, manager, oecd and user. The user group covers user profile editing and company profile visibility.

Implementation Suggestions

class Group(models.Model):
    """ contrib.auth.models """
    name = models.CharField(_("name"), max_length=150, unique=True)
    # new field 'description' for documenting intent of this group
    description = models.TextField(
        verbose_name=_("description"),
        blank=True,
    )
    permissions = models.ManyToManyField(
        Permission,
        verbose_name=_("permissions"),
        blank=True,
    )
    ...

I have tried this locally and after migration it appears to work. The documentation would need to be reviewed and I would happily do that.

[github-actions]

Thank you mdewhirst for sharing your idea! We have a lot of them so please be patient. You can see the current queue here.

Community instructions

For commenters, please use the emoji reactions on the issue to express support, and/or concern easily. Please use the comments to ask questions or contribute knowledge about the idea. It is unhelpful to post comments of "I'd love this" or "What's the state of this?"

Reaction Guide

• 👍 This is something I would use
• 👎 This is something that would cause problems for me or Django
• 😕 I’m indifferent to this
• 🎉 This is an easy win

[mdewhirst]

Here is the current docstring/documentation for the group model. The third paragraph indicates an earlier intention to use groups for purposes other than group permissions. Therefore only a minimal addition is suggested.

"""
    Groups are a generic way of categorizing users to apply permissions, or
    some other label, to those users. A user can belong to any number of
    groups.

    A user in a group automatically has all the permissions granted to that
    group. For example, if the group 'Site editors' has the permission
    can_edit_home_page, any user in that group will have that permission.

    Beyond permissions, groups are a convenient way to categorize users to
    apply some label, or extended functionality, to them. For example, you
    could create a group 'Special users', and you could write code that would
    do special things to those users -- such as giving them access to a
    members-only portion of your site, or sending them members-only email
    messages.

+    The description field is for administrators. Use it as an aide-memoire for
+    any groups with non-obvious names.
    """

The group Fields documentation would need to be enhanced perhaps saying ...

Fields[¶](https://docs.djangoproject.com/en/5.2/ref/contrib/auth/#id3)

[Group](https://docs.djangoproject.com/en/5.2/ref/contrib/auth/#django.contrib.auth.models.Group) objects have the following fields:

class models.Group

    name[¶](https://docs.djangoproject.com/en/5.2/ref/contrib/auth/#django.contrib.auth.models.Group.name)

        Required. 150 characters or fewer. Any characters are permitted. Example: 'Awesome Users'.

+    description[¶](...)
+
+        Optional. Text to explain non-obvious group name. Example: 'Users qualify as awesome if they donate ...'

    permissions[¶](https://docs.djangoproject.com/en/5.2/ref/contrib/auth/#django.contrib.auth.models.Group.permissions)

        Many-to-many field to [Permission](https://docs.djangoproject.com/en/5.2/ref/contrib/auth/#django.contrib.auth.models.Permission):

Authenticating should not be affected by having an extra field. If it was felt that inserting 'description' between 'name' and 'permissions' might be risky, 'description' could be appended to the field list instead.

If that was the case, we might need to slightly complicate matters by offering an Admin fieldset which could be edited. I haven't looked at that.

[j-osephlong]

I strongly support this as an easy win. In my organization, groups are mostly used as a way to manage user roles to determine which UI elements to reveal, and which API endpoints to restrict, based off of their real role in the company.