[JENKINS-50164] Document builds location configuration

NOT documentation the workspaces location customization on purpose: people should generally not have workspaces on `master` anyway since this would mean builds are run there.
jenkins-infra · Apr 23, 2018 · 2da6c1a · 2da6c1a
1 parent bcdd4bf
commit 2da6c1a
Showing 1 changed file with 24 additions and 0 deletions.
diff --git a/content/doc/book/architecting-for-scale.adoc b/content/doc/book/architecting-for-scale.adoc
@@ -506,6 +506,30 @@ JENKINS_HOME
          +- jobs           (sub directory for all nested jobs)
 ----
 
+[[segrate-data]]
+===== Segregating pure configuration from less durable data
+
+CAUTION: No data migration is handled by Jenkins when using those settings.
+So you either want to use them from the beginning, or make sure you take into consideration which data you would like to be moved to the right place before using the following switches.
+
+It is possible to separate customize some of the layout to better separate pure job configurations from less durable data, like build data or logs.
+footnote:[These switches are used to configure out of the box link:https://jenkins.io/blog/2018/04/06/jenkins-essentials/[Jenkins Essentials] instances.]
+
+====== Configure a different _jobs build data_ layout
+
+Historically, the configuration of a given job is located under `$JENKINS_HOME/jobs/[JOB_NAME]/config.xml` and its builds are under `$JENKINS_HOME/jobs/[JOB_NAME]/builds`.
+
+This typically makes it more impractical to set up a different backup policy, or set up a quicker disk for making builds potentially faster.
+
+For instance, if you would like to move builds under a different root, you can use the following value: `$JENKINS_VAR/${ITEM_FULL_NAME}/builds`.
+
+Note that starting with Jenkins 2.119, the User Interface for this was replaced by the `jenkins.model.Jenkins.buildsDir` system property. See the link:https://wiki.jenkins.io/display/JENKINS/Features+controlled+by+system+properties[dedicated _Features Controlled with System Properties_ wiki page] for more details.
+
+////
+NOT documenting the other jenkins.model.Jenkins.workspacesDir property on purpose, as this should generally not be used.
+Using it means one would build on the master, which we clearly do not want to encourage.
+////
+
 ==== Choosing a backup strategy
 
 All of your Jenkins-specific configurations that need to be backed up will live