jobs: README: better explain newlines curiosity and update behavior

Change-Id: I9707091a4dcfc65bd378fab02bf24692debb60ed

1 files changed, 7 insertions, 4 deletions

diff --git a/jobs/README.adoc b/jobs/README.adoc
index b18d7aa..d526771 100644
--- a/jobs/README.adoc
+++ b/jobs/README.adoc
@@ -56,12 +56,15 @@ later inserted in a 'shell' section, the newlines between individual shell
 lines don't all survive. Interestingly enough, only a line that has more
 indenting than the first line also receives an actual newline in the resulting
 jenkins Execute Shell section; take a look at the job's config page on jenkins.
-Hence we often have a '# keep first line with less indent' comment. The safest
-way to ensure the commands work is to insert ';' at the end of each and every
-shell command. Still keep '\' at the end of lines to be combined, because you
-can't rely on newlines being omitted, either.
+Hence we often have a '# keep first line with less indent' comment. Note that
+issuing backslashes to span a shell command across several lines will break the
+command if the newlines are not preserved, so we need a '# keep...' comment
+where there are more than one shell command, and where there are backslashes
+'\' to join multiple lines.
 
 - jobs named on cmdline are not updated:
 
 Make sure the job name is correct, or just issue an entire yml file without
 individual job names.
+
+Also be aware that jobs are only actually updated when anything changed.