add prepare step, as opt-in experiment. also added opt-in experiment framework.

Author: joonas-fi

cmd/bob/bobfile.go

@@ -23,6 +23,11 @@ type Bobfile struct {
 	DockerImages               []DockerImageSpec `json:"docker_images"`
 	Subrepos                   []SubrepoSpec     `json:"subrepos,omitempty"`
 	OsArches                   *OsArchesSpec     `json:"os_arches"`
+	Experiments                experiments       `json:"experiments_i_consent_to_breakage,omitempty"`
+}
+
+type experiments struct {
+	PrepareStep bool `json:"prepare_step"`
 }
 
 type SubrepoSpec struct {
@@ -69,7 +74,38 @@ func (o *OsArchesSpec) AsBuildEnvVariables() []string {
 	return ret
 }
 
+/*	Suppose you have three builders: 1) backend, 2) frontend and 3) documentation.
+	Here's the order in which the commands are executed:
+
+
+   Start ────────────────┐     ┌───────────────┐     ┌───────────────┐
+                         │     ▲               │     ▲               │
+              ┌──────────▼┐    │    ┌──────────▼┐    │    ┌──────────▼┐
+      Backend │  Prepare ││    │    │  Build   ││    │    │  Publish ││
+              └──────────┼┘    │    └──────────┼┘    │    └──────────┼┘
+                         │     │               │     │               │
+                         │     │               │     │               │
+              ┌──────────▼┐    │    ┌──────────▼┐    │    ┌──────────▼┐
+     Frontend │  Prepare ││    │    │  Build   ││    │    │  Publish ││
+              └──────────┼┘    │    └──────────┼┘    │    └──────────┼┘
+                         │     │               │     │               │
+                         │     │               │     │               │
+              ┌──────────▼┐    │    ┌──────────▼┐    │    ┌──────────▼┐
+Documentation │  Prepare ││    │    │  Build   ││    │    │  Publish ││
+              └──────────┼┘    │    └──────────┼┘    │    └──────────┼┘
+                         │     │               │     │               │
+                         │     │               │     │               │
+                         └─────┘               └─────┘               ▼
+
+	Rationale:
+
+	- backend needs some codegenerated stuff from documentation, like URLs so backend can link to documentation,
+	  so backend build can use stuff from documentation.prepare step.
+	- you'll want to publish artefacts only if all builders succeeded (*.build before *.publish),
+	  so there's no unnecessary uploads.
+*/
 type BuilderCommands struct {
+	Prepare []string `json:"prepare"`
 	Build   []string `json:"build"`
 	Publish []string `json:"publish"`
 	Dev     []string `json:"dev"`
@@ -160,6 +196,10 @@ func validateBuilders(bobfile *Bobfile) error {
 		}
 
 		alreadySeenNames[builder.Name] = Void{}
+
+		if len(builder.Commands.Prepare) > 0 && !bobfile.Experiments.PrepareStep {
+			return fmt.Errorf("%s: you need to opt-in to prepare_step experiment", builder.Name)
+		}
 	}
 
 	return nil

cmd/bob/bobfile_test.go

@@ -29,9 +29,39 @@ func TestAssertUniqueBuilderNames(t *testing.T) {
 		},
 	}
 
-	assert.Assert(t, validateBuilders(bobfileEmpty) == nil)
-	assert.Assert(t, validateBuilders(bobfileUniques) == nil)
+	assert.Ok(t, validateBuilders(bobfileEmpty))
+	assert.Ok(t, validateBuilders(bobfileUniques))
 	assert.EqualString(t,
 		validateBuilders(bobfileNonUniques).Error(),
 		"duplicate builder name: foobar")
 }
+
+func TestConsentToBreakage(t *testing.T) {
+	properConsent := &Bobfile{
+		Builders: []BuilderSpec{
+			{
+				Name: "foobar",
+				Commands: BuilderCommands{
+					Prepare: []string{"foo"},
+				},
+			},
+		},
+		Experiments: experiments{
+			PrepareStep: true,
+		},
+	}
+
+	missingConsent := &Bobfile{
+		Builders: []BuilderSpec{
+			{
+				Name: "foobar",
+				Commands: BuilderCommands{
+					Prepare: []string{"foo"},
+				},
+			},
+		},
+	}
+
+	assert.Ok(t, validateBuilders(properConsent))
+	assert.EqualString(t, validateBuilders(missingConsent).Error(), "foobar: you need to opt-in to prepare_step experiment")
+}

cmd/bob/build.go

@@ -236,7 +236,11 @@ func build(buildCtx *BuildContext) error {
 		}
 	}
 
-	// build builders (TODO: check cache so this is not done unless necessary?)
+	// build builders.
+	//
+	// it would be cool to not invoke Docker if this is cached anyway, but the analysis would have
+	// to include modification check for the Dockerfile and all of its build context, so we're just
+	// best off calling Docker build because it is the best at detecting cache invalidation.
 	for _, builder := range buildCtx.Bobfile.Builders {
 		builder := builder // pin
 
@@ -259,38 +263,40 @@ func build(buildCtx *BuildContext) error {
 		}
 	}
 
-	// two passes:
-	//   1) run all builds with all phases except publish
-	//   2) run all builds with only publish phase (but only if publish requested)
+	// three-pass process. the flow is well documented in *BuilderCommands* type
+	pass := func(opDesc string, getCommand func(cmds BuilderCommands) []string) error {
+		for _, builder := range buildCtx.Bobfile.Builders {
+			if buildCtx.BuilderNameFilter != "" && builder.Name != buildCtx.BuilderNameFilter {
+				continue
+			}
 
-	// 1)
-	for _, builder := range buildCtx.Bobfile.Builders {
-		if buildCtx.BuilderNameFilter != "" && builder.Name != buildCtx.BuilderNameFilter {
-			continue
-		}
+			cmd := getCommand(builder.Commands)
+			if len(cmd) == 0 { // no command for this step specified
+				continue
+			}
 
-		if len(builder.Commands.Build) == 0 {
-			continue
+			if err := runBuilder(builder, buildCtx, opDesc, cmd); err != nil {
+				return fmt.Errorf("%s.%s: %w", builder.Name, opDesc, err)
+			}
 		}
 
-		if err := runBuilder(builder, buildCtx, "build", builder.Commands.Build); err != nil {
-			return err
-		}
+		return nil
 	}
 
-	// 2)
-	for _, builder := range buildCtx.Bobfile.Builders {
-		if buildCtx.BuilderNameFilter != "" && builder.Name != buildCtx.BuilderNameFilter {
-			continue
-		}
+	preparePass := func(cmds BuilderCommands) []string { return cmds.Prepare }
+	buildPass := func(cmds BuilderCommands) []string { return cmds.Build }
+	publishPass := func(cmds BuilderCommands) []string { return cmds.Publish }
 
-		if !buildCtx.PublishArtefacts || len(builder.Commands.Publish) == 0 {
-			continue
-		}
+	if err := pass("prepare", preparePass); err != nil {
+		return err // err context ok
+	}
 
-		if err := runBuilder(builder, buildCtx, "publish", builder.Commands.Publish); err != nil {
-			return err
-		}
+	if err := pass("build", buildPass); err != nil {
+		return err // err context ok
+	}
+
+	if err := pass("publish", publishPass); err != nil {
+		return err // err context ok
 	}
 
 	dockerLoginCache := newDockerRegistryLoginCache()