From 1a3fefb2ac5b314cb162635576dc2fc8c938a868 Mon Sep 17 00:00:00 2001
From: David Turner <david.turner@elastic.co>
Date: Thu, 3 Dec 2020 10:55:53 +0000
Subject: [PATCH] Clarify usage of jvm.options in its comments (#61456)

Since #51882 we recommend not editing the `jvm.options` file, preferring
instead to override its contents with additional files in
`jvm.options.d`. However the inline comments in this file do not point
users in that direction. This commit adjusts these inline comments.
---
 distribution/src/config/jvm.options | 41 ++++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 10 deletions(-)

diff --git a/distribution/src/config/jvm.options b/distribution/src/config/jvm.options
index e51fb9f06f8b..99580b65c593 100644
--- a/distribution/src/config/jvm.options
+++ b/distribution/src/config/jvm.options
@@ -1,12 +1,29 @@
+################################################################
+##
 ## JVM configuration
+##
+################################################################
+##
+## WARNING: DO NOT EDIT THIS FILE. If you want to override the
+## JVM options in this file, or set any additional options, you
+## should create one or more files in the jvm.options.d
+## directory containing your adjustments.
+##
+## See https://www.elastic.co/guide/en/elasticsearch/reference/current/jvm-options.html
+## for more information.
+##
+################################################################
+
+
 
 ################################################################
 ## IMPORTANT: JVM heap size
 ################################################################
 ##
-## You should always set the min and max JVM heap
-## size to the same value. For example, to set
-## the heap to 4 GB, set:
+## You must always set the initial and maximum JVM heap size to
+## the same value. For example, to set the heap to 4 GB, create
+## a new file in the jvm.options.d directory containing these
+## lines:
 ##
 ## -Xms4g
 ## -Xmx4g
@@ -16,19 +33,22 @@
 ##
 ################################################################
 
-# Xms represents the initial size of total heap space
-# Xmx represents the maximum size of total heap space
+# Xms represents the initial size of the JVM heap
+# Xmx represents the maximum size of the JVM heap
 
 -Xms${heap.min}
 -Xmx${heap.max}
 
+
+
 ################################################################
 ## Expert settings
 ################################################################
 ##
-## All settings below this section are considered
-## expert settings. Don't tamper with them unless
-## you understand what you are doing
+## All settings below here are considered expert settings. Do
+## not adjust them unless you understand what you are doing. Do
+## not edit them in this file; instead, create a new file in the
+## jvm.options.d directory containing your adjustments.
 ##
 ################################################################
 
@@ -49,8 +69,9 @@
 
 ## heap dumps
 
-# generate a heap dump when an allocation from the Java heap fails
-# heap dumps are created in the working directory of the JVM
+# generate a heap dump when an allocation from the Java heap fails; heap dumps
+# are created in the working directory of the JVM unless an alternative path is
+# specified
 -XX:+HeapDumpOnOutOfMemoryError
 
 # specify an alternative path for heap dumps; ensure the directory exists and