Initial proposal for pipeline stage terminology

docs/vocabulary.md

@@ -22,6 +22,7 @@
   - [GitLab](#gitlab)
 - [Mapping of Terms](#mapping-of-terms)
   - [CI/CD Tools and Technologies](#cicd-tools-and-technologies)
+  - [Stages](#stages)
   - [SCM Tools and Technologies](#scm-tools-and-technologies)
 - [Shared Vocabulary](#shared-vocabulary)
 
@@ -388,6 +389,69 @@ pipeline in corresponding documentation.
 | **Tekton**         | N/A       | Step       | Task     | Pipeline | Trigger | Resource (?)           |
 | **Zuul**           | N/A       | N/A        | Job      | Pipeline | Trigger | Node (?)               |
 
+### Stages
+
+The list below is an attempt to create a mapping of common names for Stages, where a Stage is defined here as the unit of work one degree smaller than a Pipeline. (The effort of proposing a common vocabulary across CI/CD Tools and Technologies is not yet performed, but we'll use the most common term from the table above as the working term.)
+
+While CI/CD Tools and Technologies generally give developers broad leeway in naming and implementing their Stages, agreeing upon some common terms will help develop more pluggable Pipelines.
+
+The concepts below can be re-ordered in Pipeline implementations. For example, it is often the case that software linting (logically a test) is done prior to the Build Stage. Also, deployment to a staging environment is often done prior to the Release Stage, while the deployment for production often happens after the Release Stage.
+
+In Pipeline implementations, there may also be other Stages preceding or following the ones listed below.
+
+In the lists and table below, Software Artifacts includes: Documentation Source Files, Source Code, Baseline/Composition/Dependency Information, Infrastructure as Code.
+
+"Software Source" refers to human-readable source files that are inputs to the pipeline, such as: Source Code, Configuration Files, Documentation Source Files, Declared Dependencies, Baseline/Composition Information (i.e. lock files in source control)
+
+"Binary Source" refers to executables that are inputs to the pipeline, such as: Executable Software Dependencies, Container Images, Virtual Machine Images
+
+"Generated Software" refers to human-readable files that are outputs of the pipeline, such as: Compiled Software, Generated Configuration Files, Compiled Documentation, Baseline/Composition Information generated by the pipeline. 
+
+"Generated Binaries" refers to executables that are outputs of the pipeline, such as: Executable Software, Container Images, Virtual Machine Images
+
+#### Any Stage
+* Semantics: Some inputs and outputs are used across any and all stages. They're listed here once, rather than repeating them for each stage.
+* Aliases: N/A
+* Inputs: Secrets, Pipeline Environment, Pipeline Workspace, Pipeline Utility Tools
+* Outputs: Stage Results and Return Codes, Logs
+
+#### Build Stage
+* Semantics: Download, retrieve, assemble, and/or compile software into an executable and testable format. Download, retrieve, assemble, and/or compile documentation into a consumable format.
+* Aliases: Compile
+* Inputs: Software Source, Binary Source
+* Outputs: Generated Software, Generated Binaries
+* Other Results and Side Effects: The Build stage may also captur and store point-in-time details about the pipeline environment and tools (compiler versions, package manager versions, task container versions in tekton, OS versions etc.). While the pipeline configuration should ideally be in source code, in reality some settings will likely depend on external factors. Storing this information in an immutable data store facilitates debugging, rebuilds, pipeline verification, audit records, and forensics. 
+
+#### Test Stage
+* Semantics: Test, scan, verify, and lint software and documentation.
+* Aliases: Verify
+* Inputs: Software Source, Binary Source, Generated Software, Generated Binaries
+* Outputs: Test/Lint/Scan Records, Test/Lint/Scan Reports, Test/Lint/Scan Coverage Reports
+* Other Results and Side Effects: N/A
+
+#### Release Stage
+* Semantics: Package, version, sign, and publish software artifacts and documentation.
+* Aliases: Deliver, Publish
+* Inputs: Software Source, Binary Source, Generated Software, Generated Binaries, Release Approvals
+* Outputs: Release Records, Release Reports, Generated Software, Generated Binaries
+* Other Results and Side Effects: Documentation and Software: packaged, signed, and published to a repository.
+
+#### Deploy Stage
+* Semantics: Deploy software artificats and documentation to any environment other than the pipeline environment. Verify successful deployment.
+* Aliases: Install
+* Inputs: Software Source, Binary Source, Generated Software, Generated Binaries, Deployment KPIs
+* Outputs: Deployment Records, Deployment Reports, Secrets to access deployed resources
+* Other Results and Side Effects: Documentation hosted in a review, staging or production environment. Software running in a review, staging or production environment. Deployment KPIs might influence how the deployment proceeds; for example, for Canary or Blue/Green deployments.
+
+#### Inputs and Outputs for Pipeline Stages
+
+| Stage Name | Software Source | Binary Source | Generated Software | Generated Binaries | Secrets | Pipeline Environment | Pipeline Workspace | Return Codes | Results, Records and Reports | Logs |
+| :--------: | ------------------ | ---------------- | ---------------------- | ------------------- | ------- | ----------------- | ---------------- | ------------ | ---------------------------- | ---- |
+| Build | I | I | O | O | I | I | I | O | O | O |
+| Test | I | I | I | I | I | I | I | O | O | O |
+| Release | I | I | I, O | I, O | I | I | I | O | O | O |
+| Deploy | I | I | I | I | I, O | I | I | O | O | O |
+
 ### SCM Tools and Technologies
 
 The table below is an attempt to create a mapping of different terms used