Merge pull request #2136 from orrc/JENKINS-33364_configure-system

[JENKINS-33364] Core documentation: Configure System page
jenkinsci · Apr 1, 2016 · 0db4bc2 · 0db4bc2
2 parents 1258098 + 95bfaa0
commit 0db4bc2
Show file tree

Hide file tree

Showing 4 changed files with 77 additions and 36 deletions.
diff --git a/core/src/main/resources/jenkins/model/Jenkins/help-rawBuildsDir.html b/core/src/main/resources/jenkins/model/Jenkins/help-rawBuildsDir.html
@@ -1,15 +1,28 @@
 <div>
-    Specify where Jenkins would store records of the past builds.
-    This value can include the following variables.
-
+    Specifies where Jenkins will store build records on the file system. This
+    includes the console output and other metadata generated by a build.
+    <p>
+    This value may include the following variables:
     <ul>
-        <li><tt>${JENKINS_HOME}</tt> &mdash; Jenkins home directory.
-        <li><tt>${ITEM_ROOTDIR}</tt> &mdash; Root directory of a job for which the default workspace is allocated.
-        <li><tt>${ITEM_FULL_NAME}</tt> &mdash; '/'-separated job name, like "foo/bar".
+        <li><tt>${JENKINS_HOME}</tt> &mdash; Absolute path of the Jenkins home
+            directory
+        <li><tt>${ITEM_ROOTDIR}</tt> &mdash; Absolute path of the directory
+            where Jenkins stores the configuration and related metadata for a
+            given job
+        <li><tt>${ITEM_FULL_NAME}</tt> &mdash; The full name of a given job,
+            which may be slash-separated, e.g. <tt>foo/bar</tt> for the job
+            <tt>bar</tt> in folder <tt>foo</tt>
     </ul>
-
+    The value must include <tt>${ITEM_ROOTDIR}</tt> or
+    <tt>${ITEM_FULL_NAME}</tt>, so that each job can store its build records
+    separately.
+    <p>
+    Changing this value allows you to store build records on a larger, but
+    slower disk, rather than on the same disk where builds are executed.
+    <p>
+    Any changes to this value will take effect as soon as this configuration
+    page is saved, but note that Jenkins will not automatically migrate any data
+    from the current build record root directory.
     <p>
-    Changing this value allows you to put build records on a bigger but slow disk,
-    while keeping JENKINS_HOME on highly available backed up drive, for example.
-    Default value is <tt>${ITEM_ROOTDIR}/builds</tt>.
-</div>
+    The default value is <tt>${ITEM_ROOTDIR}/builds</tt>.
+</div>
diff --git a/core/src/main/resources/jenkins/model/Jenkins/help-rawWorkspaceDir.html b/core/src/main/resources/jenkins/model/Jenkins/help-rawWorkspaceDir.html
@@ -1,15 +1,30 @@
 <div>
-    Specify where Jenkins would store job workspaces on the master node.
-    (It has no effect on builds run on agents.)
-    This value can include the following variables.
-
+    Specifies where Jenkins will store workspaces for builds that are executed
+    on the master.<br>
+    It has no effect on builds that are executed on agents.
+    <p>
+    This value may include the following variables:
     <ul>
-        <li><tt>${JENKINS_HOME}</tt> &mdash; Jenkins home directory.
-        <li><tt>${ITEM_ROOTDIR}</tt> &mdash; Root directory of a job for which the default workspace is allocated.
-        <li><tt>${ITEM_FULL_NAME}</tt> &mdash; '/'-separated job name, like "foo/bar".
+        <li><tt>${JENKINS_HOME}</tt> &mdash; Absolute path of the Jenkins home
+            directory
+        <li><tt>${ITEM_ROOTDIR}</tt> &mdash; Absolute path of the directory
+            where Jenkins stores the configuration and related metadata for a
+            given job
+        <li><tt>${ITEM_FULL_NAME}</tt> &mdash; The full name of a given job,
+            which may be slash-separated, e.g. <tt>foo/bar</tt> for the job
+            <tt>bar</tt> in folder <tt>foo</tt>
     </ul>
-
+    The value should normally include <tt>${ITEM_ROOTDIR}</tt> or
+    <tt>${ITEM_FULL_NAME}</tt>, otherwise different jobs will end up sharing the
+    same workspace.
+    <p>
+    As builds tend to be disk I/O intensive, changing this value enables you to
+    put build workspaces on faster storage hardware, such as SSDs or even RAM
+    disks.
+    <p>
+    Any changes to this value will take effect as soon as this configuration
+    page is saved, but note that Jenkins will not automatically migrate any data
+    from the current workspace root directory.
     <p>
-    Changing this value allows you to put workspaces on SSD, SCSI, or even ram disks.
-    Default value is <tt>${ITEM_ROOTDIR}/workspace</tt>.
-</div>
+    The default value is <tt>${ITEM_ROOTDIR}/workspace</tt>.
+</div>
diff --git a/war/src/main/webapp/help/system-config/homeDirectory.html b/war/src/main/webapp/help/system-config/homeDirectory.html
@@ -1,17 +1,29 @@
 <div>
-  Jenkins stores all the data files inside this directory in the file system.
-  You can change this by either:
-  <ol>
+  By default, Jenkins stores all of its data in this directory on the file
+  system.
+  <br>
+  Under the <i>Advanced</i> section, you can choose to store build workspaces
+  and build records elsewhere.
+  <p>
+  There are a few ways to change the Jenkins home directory:
+  <ul>
     <li>
-      Using your web container's admin tool to set the <tt>JENKINS_HOME</tt>
-      environment entry.
+      Edit the <code>JENKINS_HOME</code> variable in your Jenkins configuration
+      file (e.g. <code>/etc/sysconfig/jenkins</code> on Red Hat Linux).
     <li>
-      Setting the environment variable <tt>JENKINS_HOME</tt> before launching
-      your web container.
+      Use your web container's admin tool to set the <code>JENKINS_HOME</code>
+      environment variable.
     <li>
-      (Not recommended) modifying web.xml in <tt>jenkins.war</tt> (or its expanded image
-      in your web container).
-  </ol>
+      Set the environment variable <code>JENKINS_HOME</code> before launching
+      your web container, or before launching Jenkins directly from the WAR file.
+    <li>
+      Set the <code>JENKINS_HOME</code> Java system property when launching your
+      web container, or when launching Jenkins directly from the WAR file.
+    <li>
+      Modify <tt>web.xml</tt> in <tt>jenkins.war</tt> (or its expanded image in
+      your web container). This is not recommended.
+  </ul>
   This value cannot be changed while Jenkins is running.
-  This entry is mostly for you to make sure that your configuration is taking effect.
+  <br>
+  It is shown here to help you ensure that your configuration is taking effect.
 </div>
diff --git a/war/src/main/webapp/help/system-config/systemMessage.html b/war/src/main/webapp/help/system-config/systemMessage.html
@@ -1,5 +1,6 @@
 <div>
-  This message will be displayed on <a href=".">the top page</a>.
-  Useful for posting a system-wide notification to users.
-  Can contain HTML tags or whatever markup language is defined for the system.
+  This message will be displayed at the top of the
+  <a href="." target="_blank">Jenkins main page</a>.
+  <p>
+  This can be useful for posting notifications to your users.
 </div>