[buildbot] phase1: documentation update

[LEDE Commits]

ynezz pushed a commit to buildbot.git, branch master:
https://git.openwrt.org/11286e4718e7e2f30705c60fe09c09c5979d7c9b

commit 11286e4718e7e2f30705c60fe09c09c5979d7c9b
Author: Thibaut VARÈNE <hacks at slashdirt.org>
AuthorDate: Thu Oct 27 20:31:19 2022 +0200

    phase1: documentation update
    
    Signed-off-by: Thibaut VARÈNE <hacks at slashdirt.org>
---
 phase1/master.cfg | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/phase1/master.cfg b/phase1/master.cfg
index 21da1a2..0c72ebd 100644
--- a/phase1/master.cfg
+++ b/phase1/master.cfg
@@ -154,6 +154,7 @@ def ini_parse_workers(section):
 			NetLocks[lockname] = locks.MasterLock(lockname)
 
 	log.msg("Configured worker: {}".format(name))
+	# NB: phase1 build factory requires workers to be single-build only
 	c['workers'].append(Worker(name, password, max_builds = 1, properties = sl_props))
 
 
@@ -164,6 +165,7 @@ for section in ini.sections():
 	if section.startswith("worker "):
 		ini_parse_workers(ini[section])
 
+# list of branches in build-priority order
 branchNames = [branches[b]["name"] for b in branches]
 
 c['protocols'] = {'pb': {'port': pb_port}}
@@ -272,6 +274,11 @@ c['prioritizeBuilders'] = prioritizeBuilders
 targets = set()
 
 def populateTargets():
+	""" fetch a shallow clone of each configured branch in turn:
+	execute dump-target-info.pl and collate the results to ensure
+	targets that only exist in specific branches get built.
+	This takes a while during master startup but is executed only once.
+	"""
 	log.msg("Populating targets, this will take time")
 	sourcegit = work_dir + '/source.git'
 	for branch in branchNames:
@@ -296,7 +303,7 @@ def populateTargets():
 populateTargets()
 
 # the 'change_source' setting tells the buildmaster how it should find out
-# about source code changes.  Here we point to the buildbot clone of pyflakes.
+# about source code changes.
 
 c['change_source'] = []
 c['change_source'].append(GitPoller(
@@ -306,9 +313,9 @@ c['change_source'].append(GitPoller(
 
 ####### SCHEDULERS
 
-# Configure the Schedulers, which decide how to react to incoming changes.  In this
-# case, just kick off a 'basebuild' build
+# Configure the Schedulers, which decide how to react to incoming changes.
 
+# Selector for known valid tags
 class TagChoiceParameter(BaseParameter):
 	spec_attributes = ["strict", "choices"]
 	type = "list"
@@ -322,11 +329,13 @@ class TagChoiceParameter(BaseParameter):
 		taglist = []
 		branchvers = []
 
+		# we will filter out tags that do no match the configured branches
 		for b in branchNames:
 			basever = re.search(r'-([0-9]+\.[0-9]+)$', b)
 			if basever:
 				branchvers.append(basever[1])
 
+		# grab tags from remote repository
 		alltags = subprocess.Popen(
 			['git', 'ls-remote', '--tags', repo_url],
 			stdout = subprocess.PIPE)
@@ -339,10 +348,12 @@ class TagChoiceParameter(BaseParameter):
 
 			(rev, tag) = line.split()
 
+			# does it match known format? ('vNN.NN.NN(-rcN)')
 			tagver = re.search(r'\brefs/tags/(v[0-9]+\.[0-9]+\.[0-9]+(?:-rc[0-9]+)?)$', tag.decode().strip())
 
-			# only list tags matching configured branches
+			# only list valid tags matching configured branches
 			if tagver and any(tagver[1][1:].startswith(b) for b in branchvers):
+				# if we want a specific tag, ignore all that don't match
 				if findtag and findtag != tagver[1]:
 					continue
 				taglist.append({'rev': rev.decode().strip(), 'tag': tagver[1]})
@@ -454,6 +465,7 @@ c['schedulers'].append(ForceScheduler(
 	),
 
 	properties = [
+		# NB: avoid nesting to simplify processing of properties
 		util.ChoiceStringParameter(
 			name    = "target",
 			label   = "Build target",
@@ -629,6 +641,8 @@ c['builders'].append(BuilderConfig(
 	workername  = "__local_force_build",
 	factory     = force_factory))
 
+
+# NB the phase1 build factory assumes workers are single-build only
 for target in targets:
 	ts = target.split('/')
 
@@ -708,6 +722,7 @@ for target in targets:
 	factory.addStep(ShellCommand(
 		name = "fetchrefs",
 		description = "Fetching Git remote refs",
+		descriptionDone = "Git remote refs fetched",
 		command = ["git", "fetch", "origin", Interpolate("+refs/heads/%(prop:branch)s:refs/remotes/origin/%(prop:branch)s")],
 		haltOnFailure = True,
 	))
@@ -716,7 +731,8 @@ for target in targets:
 	# Ref: https://web.archive.org/web/20190729224316/http://lists.infradead.org/pipermail/openwrt-devel/2019-June/017809.html
 	factory.addStep(ShellCommand(
 		name = "gitverify",
-		description = "Ensure that Git HEAD is pointing to a branch or tag",
+		description = "Ensuring that Git HEAD is pointing to a branch or tag",
+		descriptionDone = "Git HEAD is sane",
 		command = 'git rev-parse --abbrev-ref HEAD | grep -vxqF HEAD || git show-ref --tags --dereference 2>/dev/null | sed -ne "/^$(git rev-parse HEAD) / { s|^.*/||; s|\\^.*||; p }" | grep -qE "^v[0-9][0-9]\\."',
 		haltOnFailure = True,
 	))
@@ -805,7 +821,7 @@ for target in targets:
 		want_stdout = False,
 		want_stderr = False,
 		haltOnFailure = True,
-		flunkOnFailure = False,	# this is not a build FAILURE
+		flunkOnFailure = False,	# this is not a build FAILURE - TODO mark build as SKIPPED
 	))
 
 	# find libc suffix