Refine content and appearance of the user account screen (#9521)

Co-authored-by: Tim Jacomb <[email protected]>

core/src/main/java/hudson/model/TimeZoneProperty.java

@@ -62,6 +62,11 @@ public String getDisplayName() {
             return Messages.TimeZoneProperty_DisplayName();
         }
 
+        @Override
+        public String getDescription() {
+            return Messages.TimeZoneProperty_Description();
+        }
+
         @Override
         public UserProperty newInstance(User user) {
             return new TimeZoneProperty();

core/src/main/java/hudson/model/UserPropertyDescriptor.java

@@ -26,6 +26,7 @@
 
 import edu.umd.cs.findbugs.annotations.CheckForNull;
 import edu.umd.cs.findbugs.annotations.NonNull;
+import edu.umd.cs.findbugs.annotations.Nullable;
 import hudson.model.userproperty.UserPropertyCategory;
 import java.util.Optional;
 import org.jenkinsci.Symbol;
@@ -126,4 +127,15 @@ public boolean isEnabled() {
     protected @CheckForNull String getUserPropertyCategoryAsString() {
         return null;
     }
+
+    /**
+     * Optional description for the configurable object
+     * Displays as plain text
+     *
+     * @since TODO
+     */
+    @Nullable
+    public String getDescription() {
+        return null;
+    }
 }

core/src/main/java/jenkins/console/ConsoleUrlProviderUserProperty.java

@@ -65,6 +65,11 @@ public String getDisplayName() {
             return Messages.consoleUrlProviderDisplayName();
         }
 
+        @Override
+        public String getDescription() {
+            return Messages.consoleUrlProviderDisplayName_Description();
+        }
+
         @Override
         public UserProperty newInstance(User user) {
             return new ConsoleUrlProviderUserProperty();

core/src/main/resources/hudson/model/Messages.properties

@@ -408,7 +408,8 @@ Jenkins.IsRestarting=Jenkins is restarting
 User.IllegalUsername="{0}" is prohibited as a username for security reasons.
 User.IllegalFullname="{0}" is prohibited as a full name for security reasons.
 
-TimeZoneProperty.DisplayName=User Defined Time Zone
+TimeZoneProperty.DisplayName=Time zone
+TimeZoneProperty.Description=Select a time zone to use rather than the system default
 TimeZoneProperty.DisplayDefaultTimeZone=Default
 TimeZoneProperty.current_time_in_=Current time in {0}: {1}
 TimeZoneProperty.current_time_on_server_in_in_proposed_di=Current time on server in {0}: {1}; in proposed display zone: {2}

core/src/main/resources/hudson/model/TimeZoneProperty/config.jelly

@@ -23,7 +23,7 @@ THE SOFTWARE.
 
 <?jelly escape-by-default='true'?>
 <j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
-  <f:entry field="timeZoneName" title="${%title}">
+  <f:entry field="timeZoneName">
     <f:select />
   </f:entry>
 </j:jelly>

core/src/main/resources/hudson/model/userproperty/UserPropertyCategoryAccountAction/index.jelly

@@ -30,7 +30,7 @@ THE SOFTWARE.
     <l:layout permission="${app.ADMINISTER}" title="${%title}">
         <st:include page="sidepanel.jelly" it="${it.targetUser}" />
         <l:main-panel>
-            <f:form method="post" action="configSubmit" name="config">
+            <f:form method="post" action="configSubmit" name="config" class="jenkins-form">
                 <h1>
                     ${%title}
                 </h1>
@@ -39,18 +39,20 @@ THE SOFTWARE.
                 <j:set var="it" value="${thisAction.targetUser}" />
                 <j:set var="instance" value="${it}"/>
 
-                <f:entry title="${%Full name}" help="/help/user/fullName.html">
-                    <f:textbox field="fullName" />
-                </f:entry>
-                <f:entry title="${%Description}" help="/help/user/description.html">
-                    <f:textarea field="description" codemirror-mode="${app.markupFormatter.codeMirrorMode}" codemirror-config="${app.markupFormatter.codeMirrorConfig}" previewEndpoint="/markupFormatter/previewDescription" />
-                </f:entry>
+                <f:section>
+                    <f:entry title="${%Full name}" description="${%Full name.Description}">
+                        <f:textbox field="fullName" />
+                    </f:entry>
+                    <f:entry title="${%Description}" description="${%Description.Description}">
+                        <f:textarea field="description" codemirror-mode="${app.markupFormatter.codeMirrorMode}" codemirror-config="${app.markupFormatter.codeMirrorConfig}" previewEndpoint="/markupFormatter/previewDescription" />
+                    </f:entry>
+                </f:section>
 
                 <j:set var="descriptors" value="${thisAction.myCategoryDescriptors}" />
                 <j:set var="instances" value="${it.properties}" />
                 <j:forEach var="d" items="${descriptors}" varStatus="loop">
                     <j:if test="${d.enabled}">
-                        <f:section title="${d.displayName}">
+                        <f:section title="${d.displayName}" description="${d.description}">
                             <j:set var="descriptor" value="${d}" />
                             <j:set var="instance" value="${instances[d]}" />
 

core/src/main/resources/hudson/model/userproperty/UserPropertyCategoryAccountAction/index.properties

@@ -21,5 +21,7 @@
 # THE SOFTWARE.
 
 title=Account
-Full\ name=Full Name
+Full\ name=Full name
+Full\ name.Description=We recommend using your real name so people can recognize you instead of your ID
 Description=Description
+Description.Description=Enter a short description about yourself so that visitors know who you are

core/src/main/resources/jenkins/console/ConsoleUrlProviderUserProperty/config.jelly

@@ -5,9 +5,6 @@
           <!-- Dummy field to always have an entry in form submissions so users can delete all providers. -->
           <f:checkbox field="unused" checked="true" />
         </f:invisibleEntry>
-        <f:block>
-            ${%description}
-        </f:block>
         <f:entry>
             <f:repeatableHeteroProperty field="providers" hasHeader="true" oneEach="true" header="${%Providers}" />
         </f:entry>

core/src/main/resources/jenkins/console/Messages.properties

@@ -1,2 +1,3 @@
 consoleUrlProviderDisplayName=Console URL Provider
+consoleUrlProviderDisplayName.Description=Select which view you want to use for build console links. Views listed higher will be prioritized over those listed lower. The views you choose here will be used rather than those set by administrators.
 defaultProviderDisplayName=Default

core/src/main/resources/lib/form/section.jelly

@@ -32,6 +32,9 @@ THE SOFTWARE.
       If null is given, the entire <f:section> tag becomes no-op.
       ]]>
     </st:attribute>
+    <st:attribute name="description" since="TODO">
+      Optional attribute to set a description for the section
+    </st:attribute>
     <st:attribute name="icon">
       Optional attribute to set an icon for the section, this is only visible when using section-to-sidebar-items.js
     </st:attribute>
@@ -50,6 +53,11 @@ THE SOFTWARE.
           ${attrs.title}
         </div>
       </j:if>
+      <j:if test="${attrs.description != null}">
+        <div class="jenkins-section__description">
+          ${attrs.description}
+        </div>
+      </j:if>
       <d:invokeBody />
     </section>
   </f:rowSet>

war/src/main/scss/components/_section.scss

@@ -34,6 +34,13 @@
   font-weight: 500;
 }
 
+.jenkins-section__description {
+  // Tweaked margin so that it appears visually centred when placed next to `.jenkins-section__title`
+  margin: -0.5rem 0 1rem;
+  color: var(--text-color-secondary);
+  line-height: 1.66;
+}
+
 .jenkins-section__items {
   display: grid;
   grid-template-columns: 1fr;