phase1: documentation update

Signed-off-by: Thibaut VARÈNE <hacks@slashdirt.org>

diff --git a/phase1/master.cfg b/phase1/master.cfg
index 21da1a2e35eb24f4957b60ff6ade07498fe668ba..0c72ebdd65a5350061de7030117a6101881281ca 100644 (file)
--- 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