3634: Update admin table descriptions [AB] (#3760)

* Update admin table descriptions

* Add Host rename migration

src/registrar/migrations/0147_alter_hostip_options.py

@@ -0,0 +1,17 @@
+# Generated by Django 4.2.20 on 2025-04-29 21:17
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("registrar", "0146_remove_domainrequest_eop_stakeholder_email_and_more"),
+    ]
+
+    operations = [
+        migrations.AlterModelOptions(
+            name="hostip",
+            options={"verbose_name": "Host IP", "verbose_name_plural": "Host IPs"},
+        ),
+    ]

src/registrar/models/host_ip.py

@@ -14,6 +14,10 @@ class HostIP(TimeStampedModel):
     available when registry is not available.
     """
 
+    class Meta:
+        verbose_name = "Host IP"
+        verbose_name_plural = "Host IPs"
+
     address = models.CharField(
         max_length=46,
         null=False,

src/registrar/templates/admin/model_descriptions.html

@@ -36,6 +36,20 @@
         {% include "django/admin/includes/descriptions/portfolio_invitation_description.html" %}
     {% elif opts.model_name == 'allowedemail' %}
         {% include "django/admin/includes/descriptions/allowed_email_description.html" %}
+    {% elif opts.model_name == 'federalagency' %}
+        {% include "django/admin/includes/descriptions/federal_agency_description.html" %}
+    {% elif opts.model_name == 'hostip' %}
+        {% include "django/admin/includes/descriptions/host_ip_description.html" %}
+    {% elif opts.model_name == 'portfolio' %}
+        {% include "django/admin/includes/descriptions/portfolio_description.html" %}
+    {% elif opts.model_name == 'seniorofficial' %}
+        {% include "django/admin/includes/descriptions/senior_official_description.html" %}
+    {% elif opts.model_name == 'suborganization' %}
+        {% include "django/admin/includes/descriptions/suborganization_description.html" %}
+    {% elif opts.model_name == 'waffleflag' %}
+        {% include "django/admin/includes/descriptions/waffle_flag_description.html" %}
+    {% elif opts.model_name == 'domaingroup' %}
+        {% include "django/admin/includes/descriptions/domain_group_description.html" %}
     {% else %}
         <p>This table does not have a description yet.</p>
     {% endif %}

src/registrar/templates/django/admin/includes/descriptions/allowed_email_description.html

@@ -1,6 +1,12 @@
-<p>This table is an email allow list for <strong>non-production</strong> environments.</p>
 <p>
-    If an email is sent out and the email does not exist within this table (or is not a subset of it), 
+    This table contains all email addresses that have been added to the allowlist for 
-    then no email will be sent.
+    <strong>non-production</strong> environments.
+</p>
+<p>
+    If an email is triggered and the intended recipient doesn’t appear within this table 
+    (or isn’t a subset of an entry in this table), then the message won’t be sent to that email address.
+</p>
+<p>
+    If this table is populated in a production environment, it won’t have an effect on sending emails and 
+    will simply be ignored.
 </p>
-<p>If this table is populated in a production environment, no change will occur as it will simply be ignored.</p>

src/registrar/templates/django/admin/includes/descriptions/contact_description.html

@@ -1,10 +1,8 @@
 <p>
-Contacts include anyone who has access to the registrar (known as “users”) and anyone listed in a domain request, 
+    This table contains anyone listed in a non-portfolio domain request, including other employees 
-including other employees and senior officials. 
+    and senior officials. They aren't necessarily users with an account for the registrar unless 
-Only contacts who have access to the registrar will have 
+    they are also in the <a class="text-underline" href="{% url 'admin:registrar_user_changelist' %}">Users</a> table.
-a corresponding record within the <a class="text-underline" href="{% url 'admin:registrar_user_changelist' %}">Users</a> table.
 </p>
-
 <p>
-Updating someone’s contact information here will not affect that person’s Login.gov information.
+    Updating someone’s contact information here will not affect that person’s User record or Login.gov information.
 </p>

src/registrar/templates/django/admin/includes/descriptions/domain_group_description.html

@@ -0,0 +1 @@
+<p>This table isn’t being used in the registrar yet and can be ignored.</p>

src/registrar/templates/django/admin/includes/descriptions/domain_request_description.html

@@ -1,11 +1,36 @@
 <p>
-This table contains all domain requests that have been started within the registrar and the status of those requests. 
+    This table contains all .gov domain requests. If a green checkmark appears next to the “requested domain” 
-Updating values here will immediately update the corresponding values that users see in the registrar. 
+    in this table, then it came from a portfolio organization. Updating values in this table will immediately 
+    update the corresponding values that users see in the registrar. 
 </p>
 
 <p>
-Once a domain request has been adjudicated, the details of that request should not be modified. 
+    A domain request will have one of the following 
-To update attributes (like an organization’s name) after a domain’s approval, 
+    <a class="text-underline" href="https://get.gov/help/domain-requests/#check-the-status-of-your-domain-request">statuses</a>:
-go to <a class="text-underline" href="{% url 'admin:registrar_domain_changelist' %}">Domains</a>. 
+</p>
-Similar fields display on each Domain page, but edits made there will not affect the corresponding domain request.
+<ul>
+    <li>Started</li>
+    <li>Submitted *</li>
+    <li>In review</li>
+    <li>Action needed *</li>
+    <li>Rejected *</li>
+    <li>Withdrawn *</li>
+    <li>Ineligible</li>
+    <li>Approved *</li>
+</ul>
+
+<p>
+    If you change the status to one of those marked with an asterisk, then an email will be sent to the creator of that request.
+</p>
+<p>
+    Once a domain request has been adjudicated (i.e., set to Rejected, Withdrawn, Ineligible, or Approved), the details of that 
+    request should not be modified. To update attributes (like an organization’s name) after a domain’s approval, go to 
+    <a class="text-underline" href="{% url 'admin:registrar_domain_changelist' %}">Domains</a>. Similar fields display on each 
+    domain page, but edits made there will not affect the corresponding request.
+</p>
+
+<p>
+    If a domain is accidentally approved, an entry will be added to the 
+    <a class="text-underline" href="{% url 'admin:registrar_domain_changelist' %}">Domains</a> table and an approval email will 
+    be sent. However, if the status is changed back before name servers are added, the request can be processed normally.
 </p>

src/registrar/templates/django/admin/includes/descriptions/federal_agency_description.html

@@ -0,0 +1,21 @@
+<p>This table is used to populate “federal agency” drop-down menus in the registrar and in the following Django tables:</p>
+
+<ul>
+    <li>
+        <a class="text-underline" href="{% url 'admin:registrar_domainrequest_changelist' %}">Domain requests</a>
+    </li>
+    <li>
+        <a class="text-underline" href="{% url 'admin:registrar_domain_changelist' %}">Domains</a>
+    </li>
+    <li>
+        <a class="text-underline" href="{% url 'admin:registrar_portfolio_changelist' %}">Portfolios</a>
+    </li>
+    <li>
+        <a class="text-underline" href="{% url 'admin:registrar_seniorofficial_changelist' %}">Senior officials</a>
+    </li>
+</ul>
+
+<p>
+    If a federal agency name is incorrect or needs to be changed, you should edit the existing record rather than create a 
+    new one. That way relationships with that record do not break within other Django tables.
+</p>

src/registrar/templates/django/admin/includes/descriptions/host_ip_description.html

@@ -0,0 +1,5 @@
+<p>
+    This table contains all IP addresses associated with name servers for .gov domains. 
+    A single name server can have multiple IP addresses in any combination of ip v4 or v6. 
+    This table is primarily used for troubleshooting.
+</p>

src/registrar/templates/django/admin/includes/descriptions/portfolio_description.html

@@ -0,0 +1,10 @@
+<p>
+    This table contains all portfolios in the registrar. 
+    Portfolios are used to group an organization with all its domains, requests, suborganizations, and members.
+</p>
+
+<p>
+    For portfolio organizations, the mailing address is stored in this table, and the senior official is listed in the 
+    <a class="text-underline" href="{% url 'admin:registrar_seniorofficial_changelist' %}">Senior officials</a> table. 
+    For non-portfolio organizations, that information is managed at the domain or request level.
+</p>

src/registrar/templates/django/admin/includes/descriptions/senior_official_description.html

@@ -0,0 +1,11 @@
+<p>This table includes all senior officials that can be associated with a portfolio organization.</p>
+
+<p>
+    To maintain data integrity, each organization should have only one senior official. 
+    When adding a new senior official, selecting a federal agency will automatically link the official to that agency’s portfolio.
+</p>
+
+<p>
+    The senior official for non-portfolio organizations is managed at the domain or request level. 
+    Those contacts do not appear in this table.
+</p>

src/registrar/templates/django/admin/includes/descriptions/suborganization_description.html

@@ -0,0 +1,9 @@
+<p>
+    This table contains all suborganizations created for portfolio organizations. 
+    A suborganization is any entity (agency, bureau, office) that falls under the overarching organization. 
+</p>
+
+<p>
+    Domains or requests within a portfolio can be linked to a suborganization. 
+    If linked, the suborganization’s name will be publicly shown as the domain registrant.
+</p>

src/registrar/templates/django/admin/includes/descriptions/user_portfolio_permission_description.html

@@ -8,4 +8,4 @@
 
 <p>
     If you add or remove someone to a portfolio by using this table, those actions won’t trigger notification emails.
-</p>
+</p>

src/registrar/templates/django/admin/includes/descriptions/waffle_flag_description.html

@@ -0,0 +1,13 @@
+<p>Waffle flags control whether certain features are turned on or off in the registrar.</p>
+
+<p>
+    You can adjust settings for specific user groups (superusers, staff), but the setting for "Everyone" 
+    takes priority and overrides individual group settings. 
+</p>
+
+<p>If “Everyone” is set to:</p>
+<ul>
+    <li><strong>Unknown</strong> > the system will use the specific settings for each user group</li>
+    <li><strong>No</strong> > the feature will be turned off for all user groups</li>
+    <li><strong>Yes</strong> > the feature will be turned on for all user groups</li>
+</ul>

src/registrar/tests/test_admin.py

@@ -3536,7 +3536,7 @@ class TestContactAdmin(TestCase):
         self.assertEqual(response.status_code, 200)
 
         # Test for a description snippet
-        self.assertContains(response, "Contacts include anyone who has access to the registrar (known as “users”)")
+        self.assertContains(response, "This table contains anyone listed in a non-portfolio domain request")
         self.assertContains(response, "Show more")
 
     def test_readonly_when_restricted_staffuser(self):
@@ -3867,7 +3867,7 @@ class TestFederalAgencyAdmin(TestCase):
         self.assertEqual(response.status_code, 200)
 
         # Test for a description snippet
-        self.assertContains(response, "This table does not have a description yet.")
+        self.assertContains(response, "If a federal agency name is incorrect")
         self.assertContains(response, "Show more")
 
 

src/registrar/tests/test_admin_request.py

@@ -294,7 +294,7 @@ class TestDomainRequestAdmin(MockEppLib):
         self.assertEqual(response.status_code, 200)
 
         # Test for a description snippet
-        self.assertContains(response, "This table contains all domain requests")
+        self.assertContains(response, "This table contains all .gov domain requests")
         self.assertContains(response, "Show more")
 
     @less_console_noise_decorator