From 068ed25a2a4a0357d5736883fdd439e0bf5f5764 Mon Sep 17 00:00:00 2001
From: Neels Hofmeyr <neels@hofmeyr.de>
Date: Wed, 1 Nov 2017 01:34:24 +0100
Subject: jobs: README: better explain newlines curiosity and update behavior

Change-Id: I9707091a4dcfc65bd378fab02bf24692debb60ed
---
 jobs/README.adoc | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

(limited to 'jobs/README.adoc')

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.
-- 
cgit v1.2.3

