Initial proposal for pipeline stage terminology

docs/vocabulary.md

@@ -388,6 +388,75 @@ 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 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 build. 
+
+"Generated Binaries" refers to executables that are outputs of the pipeline, such as: Executable Software, Container Images, Virtual Machine Images
+
+#### Build Stage
+* Semantics: Set up the build workspace and provision build resources. 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: N/A
+
+#### 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
+* Outputs: Release Records, Release Reports
+* 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 build environment. Verify successful deployment.
+* Aliases: Install
+* Inputs: Software Source, Binary Source, Generated Software, Generated Binaries
+* 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.
+
+#### Maintain Stage
+* Semantics: Automatically update or upgrade previously built software. May invoke some or all of the previous stages.
+* Aliases: Update, Upgrade
+* Inputs: See Above
+* Outputs: See Above
+* Other Results and Side Effects: Updated documentation and software built, tested, released and deployed. This stage can also update source code repositories, for example, with new Declared Dependencies or Baseline/Composition Information. 
+
+#### Any Stage
+* Semantics: Some inputs and outputs are used across any and all stages.
+* Aliases: N/A
+* Inputs: Secrets, Build Environment, Build Workspace
+* Outputs: Stage Results and Return Codes, Logs
+
+#### Inputs and Outputs for Pipeline Stages
+
+| Stage Name | Software Source | Binary Source | Generated Software | Generated Binaries | Secrets | Build Environment | Build 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 | I | I | I | I | O | O | O |
+| Deploy | I | I | I | I | I, O | I | I | O | O | O |
+| Maintain | I | I | I, O | I, O | 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