Update the pipeline item docs and rename MergeablePipelineItem

Signed-off-by: Vadim Markovtsev <vadim@sourced.tech>

cmd/hercules/combine.go

@@ -93,9 +93,9 @@ func loadMessage(fileName string, repos *[]string) (
 			errs = append(errs, fileName+": item not found: "+key)
 			continue
 		}
-		mpi, ok := summoned[0].(hercules.MergeablePipelineItem)
+		mpi, ok := summoned[0].(hercules.ResultMergeablePipelineItem)
 		if !ok {
-			errs = append(errs, fileName+": "+key+": MergeablePipelineItem is not implemented")
+			errs = append(errs, fileName+": "+key+": ResultMergeablePipelineItem is not implemented")
 			continue
 		}
 		msg, err := mpi.Deserialize(val)
@@ -140,7 +140,7 @@ func mergeResults(mergedResults map[string]interface{},
 			mergedResults[key] = val
 			continue
 		}
-		item := hercules.Registry.Summon(key)[0].(hercules.MergeablePipelineItem)
+		item := hercules.Registry.Summon(key)[0].(hercules.ResultMergeablePipelineItem)
 		mergedResult = item.MergeResults(mergedResult, val, mergedCommons, anotherCommons)
 		mergedResults[key] = mergedResult
 	}

core.go

@@ -39,8 +39,8 @@ type FeaturedPipelineItem = core.FeaturedPipelineItem
 // LeafPipelineItem corresponds to the top level pipeline items which produce the end results.
 type LeafPipelineItem = core.LeafPipelineItem
 
-// MergeablePipelineItem specifies the methods to combine several analysis results together.
-type MergeablePipelineItem = core.MergeablePipelineItem
+// ResultMergeablePipelineItem specifies the methods to combine several analysis results together.
+type ResultMergeablePipelineItem = core.ResultMergeablePipelineItem
 
 // CommonAnalysisResult holds the information which is always extracted at Pipeline.Run().
 type CommonAnalysisResult = core.CommonAnalysisResult

doc/PIPELINE_ITEMS.md

@@ -4,6 +4,7 @@ Pipeline items
 ### PipelineItem lifecycle
 
 ```go
+// PipelineItem is the interface for all the units in the Git commits analysis pipeline.
 type PipelineItem interface {
 	// Name returns the name of the analysis.
 	Name() string
@@ -25,6 +26,15 @@ type PipelineItem interface {
 	// "commit" and "index".
 	// Returns the calculated entities which match Provides().
 	Consume(deps map[string]interface{}) (map[string]interface{}, error)
+	// Fork clones the item the requested number of times. The data links between the clones
+	// are up to the implementation. Needed to handle Git branches. See also Merge().
+	// Returns a slice with `n` fresh clones. In other words, it does not include the original item.
+	Fork(n int) []PipelineItem
+	// Merge combines several branches together. Each is supposed to have been created with Fork().
+	// The result is stored in the called item, thus this function returns nothing.
+	// Merge() must update all the branches, not only self. When several branches merge, some of
+	// them may continue to live, hence this requirement.
+	Merge(branches []PipelineItem)
 }
 ```
 
@@ -33,6 +43,7 @@ type PipelineItem interface {
 ### LeafPipelineItem lifecycle
 
 ```go
+// LeafPipelineItem corresponds to the top level pipeline items which produce the end results.
 type LeafPipelineItem interface {
 	PipelineItem
 	// Flag returns the cmdline name of the item.
@@ -45,3 +56,18 @@ type LeafPipelineItem interface {
 ```
 
 ![LeafPipelineItem](leaf_pipeline_item.png)
+
+### MergeablePipelineItem ability (optional for LeafPipelineItem-s)
+
+```go
+// ResultMergeablePipelineItem specifies the methods to combine several analysis results together.
+type ResultMergeablePipelineItem interface {
+	LeafPipelineItem
+	// Deserialize loads the result from Protocol Buffers blob.
+	Deserialize(pbmessage []byte) (interface{}, error)
+	// MergeResults joins two results together. Common-s are specified as the global state.
+	MergeResults(r1, r2 interface{}, c1, c2 *CommonAnalysisResult) interface{}
+}
+```
+
+![ResultMergeablePipelineItem](result_mergeable_pipeline_item.png)

doc/leaf_pipeline_item.dot

@@ -12,6 +12,12 @@ digraph PipelineItem {
   Initialize -> Consume
   Commits -> Consume
   Consume -> Consume
+  Consume -> Fork
+  Fork -> Consume
+  Consume -> Merge
+  Merge -> Consume
+  Merge -> "<disposal>"
+  Merge -> Finalize
   Consume -> Finalize
   Finalize -> Result
   Result -> Serialize
@@ -25,4 +31,4 @@ digraph PipelineItem {
   Result [style=filled, fillcolor=gray]
   YAML [style=filled, fillcolor=gray]
   "Protocol Buffers" [style=filled, fillcolor=gray]
-}
+}

doc/pipeline_item.dot

@@ -11,6 +11,11 @@ digraph PipelineItem {
   Initialize -> Consume
   Commits -> Consume
   Consume -> Consume
+  Consume -> Fork
+  Fork -> Consume
+  Consume -> Merge
+  Merge -> Consume
+  Merge -> "<disposal>"
   Registration [style=filled, fillcolor=dimgray, fontcolor=white]
   Resolution [style=filled, fillcolor=dimgray, fontcolor=white]
   "Command Line" [style=filled, fillcolor=dimgray, fontcolor=white]

doc/result_mergeable_pipeline_item.dot

@@ -0,0 +1,13 @@
+digraph PipelineItem {
+  YAML -> Deserialize
+  "Protocol Buffers" -> Deserialize
+  Deserialize -> Result
+  Result -> MergeResults
+  MergeResults -> Result
+  Result -> Serialize
+  Serialize -> YAML
+  Serialize -> "Protocol Buffers"
+  Result [style=filled, fillcolor=gray]
+  YAML [style=filled, fillcolor=gray]
+  "Protocol Buffers" [style=filled, fillcolor=gray]
+}

internal/core/pipeline.go

@@ -133,8 +133,8 @@ type LeafPipelineItem interface {
 	Serialize(result interface{}, binary bool, writer io.Writer) error
 }
 
-// MergeablePipelineItem specifies the methods to combine several analysis results together.
-type MergeablePipelineItem interface {
+// ResultMergeablePipelineItem specifies the methods to combine several analysis results together.
+type ResultMergeablePipelineItem interface {
 	LeafPipelineItem
 	// Deserialize loads the result from Protocol Buffers blob.
 	Deserialize(pbmessage []byte) (interface{}, error)