4 files changed, 189 insertions, 87 deletions
diff --git a/docs/scenario-lifecycle/creating-scenarios.rst b/docs/scenario-lifecycle/creating-scenarios.rst
index f445a00..dbff9c1 100644
--- a/docs/scenario-lifecycle/creating-scenarios.rst
+++ b/docs/scenario-lifecycle/creating-scenarios.rst
@@ -6,40 +6,47 @@
 Creating Scenarios
 --------------------
 
-Purpose
-^^^^^^^^^^^
+General
+^^^^^^^^^
 
 A new scenario needs to be created, when a new combination of upstream
 components or features shall be supported, that cannot be provided with the
 existing scenarios in parallel to their existing features.
 
 Typically new scenarios are created as children of existing scenarios.
+They start as specific scenario and as they mature, they either merge back
+their features to the parent or promote to a generic scenario.
 
-* In some cases an upstream implementation can be replaced by a different solution.
-  The most obvious example here is the SDN controller. In the first OPNFV release,
-  only ODL was supported. Later ONOS and OpenContrail were added, thus creating
-  new scenarios.
+Scenario Owners
+^^^^^^^^^^^^^^^^
 
-  In most cases, only one of the SDN controllers is needed, thus OPNFV will support
-  the different SDN controllers by different scenarios. This support will be long-
-  term, so there will be multiple generic scenarios for these options.
+Each scenario must have an "owner". Scenario owners have the following responsibilities:
 
-* Another usecase is feature incompatibilities. For instance, OVS and FD.io
-  cannot be combined today. Therefore we need different scenarios for them.
-  If it is expected that such an incompatibility is not solved for longer time,
-  there can be even separate generic scenarios for these options.
+* The scenario owner is responsible for the contents and usage of the scenario.
+* He shall define the contents for the scenario deployment:
 
-The overlap between scenarios should only be allowed where they add components
-that cannot be integrated in a single deployment.
+  * The components and their versions that need to be deployed
+  * Options for the deployment of such components, e.g. settings, optional features, ..
+  * Which installers to use
+  * Deployment options (HA, NOHA, hardware types, ..)
 
-If scenario A completely covers scenario B, support of scenario B will be
-only provided as long as isolation of development risks is necessary.
-However, there might be cases where somebody wants to use scenario B
-still as a parent for specific scenarios.
+* He shall define the usage of the scenario in the development process:
 
-This is especially the case for generic scenarios, since they need more CI and testing
-resources. Therefore a gating process will be introduced for generic scenarios.
+  * Initiate integration to CI
+  * Define which testcases to run
+  * Applies that the scenario joins a release
 
+* The owner maintains the Scenario Descriptor File (SDF)
+* Drives for the scenario be supported by more installers
+
+The scenario owner of a specific scenario typically comes from the feature project
+that develops the features introduced by the scenario.
+
+The scenario owner of a generic scenario will need to drive more integration tasks than
+feature development. Thus he typically will come from a project with a broader scope
+than a single feature, e.g. a testing project.
+The scenario owner of a generic scenario needs to cover issues of all installers, so
+only in exceptional cases he will come from an installer project.
 
 Creating Generic Scenarios
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -80,16 +87,17 @@ support might be low priority during a final release preparation, e.g. after a M
   a release, when he expects the scenario merge to other scenarios, and he expects
   the features may be made available in generic scenarios.
   A scenario can join a release at the MS0 after its creation.
-  It should join a release latest on the next MS0 6 month after its
-  creation (that is it should skip only one release) and merge to its parent
-  maximum 2 releases later.
-  .. Editors note: "2 releases" is rather strict maybe refine?
 * The PTL should explain the infrastructure requirements and clarify that sufficient
   resources are available for the scenario.
 * The PTL shall assign a scenario owner.
 * The scenario owner shall maintain the scenario descriptor file according to the
   template.
-* The scenario owner shall initiate the scenario be integrated in CI or releases.
+* The scenario owner shall drive the necessary discussions with installers and testing
+  teams to get their support.
+* In case the scenario needs new keywords in the SDF, the scenario owner shall discuss
+  those with the installer teams and CI.
+* The scenario owner shall initiate the scenario be integrated in CI and 
+  participate in releases.
 * When the scenario joins a release this needs to be done in time for the relevant
   milestones.
 
diff --git a/docs/scenario-lifecycle/current-status.rst b/docs/scenario-lifecycle/current-status.rst
index 08a3776..c8da13a 100644
--- a/docs/scenario-lifecycle/current-status.rst
+++ b/docs/scenario-lifecycle/current-status.rst
@@ -6,7 +6,8 @@
 Current Status
 ---------------
 
-tdb: this chapter will summarize the scenario analysis.
+This chapter summarizes the scenario analysis to provide some background.
+It also defines the way to introduce the scenario processes.
 
 Arno
 ^^^^^^^^
@@ -18,31 +19,55 @@ that could be deployed in two ways, by the two installers available in Arno.
 Brahmaputra
 ^^^^^^^^^^^^^^^^
 
-tbd
+In Brahmaputra, we added options for SDN (ONOS, OCL) and some optional
+features (sfc, sdnvpn, kvm, l3 enabled ODL).
+Thus we had 9 scenarios, some of them to be deployed with 2 installers,
+that planned to participate in the release. Not all of them succeeded.
 
 Colorado
 ^^^^^^^^^^^^
 
-tbd
+In Colorado more components and features were added to a total of 17
+combinations of components and features. Some were supported by one
+of the four installers, others by multiple installers. In addition HA
+and NOHA options were defined.
+This lead to 28 combinations that planned to participate.
 
 Danube
 ^^^^^^^^^^
 
-tbd: Analysis of the 58 scenarios
-The analysis can be found in the slides at
-https://wiki.opnfv.org/display/INF/Scenario+Consolidation
-and will be explain with some text here.
-The text will also use the diagrams from the slides, e.g.
-show a scenario tree:
+In Danube the number of combinations of components and features increased
+to 24, but since installer support increased and more scenarios planned
+to provide HA and NOHA options, the number of combinations was 54.
 
-.. figure:: scenario-tree.png
+In addition to that some scenarios were defined later in during development
+and some scenarios worked on ARM support.
 
-and an idea about possible generic scenarios:
+This created the need to better understand relationships and
+incompatibilities of the scenarios to drive for a manageable process
+for scenarios.
 
-.. figure:: scenario-tree+idea.png
+As a result the relationship between the scenarios can be
+visualized by a scenario tree.
 
-as well as possible ways to reach this.
+.. figure:: scenario-tree-danube.png
 
+The process for generic and specific scenarios is not in place for the
+Danube release yet. But the different branches of the scenario tree
+provide the candidates to define generic scenario during the timeframe
+of the next release.
+
+Euphrates
+^^^^^^^^^^
+
+tbd: statistics on Euphrates Scenarios
+
+During Euphrates timeframe, dynamic POD allocation is introduced in CI.
+This is a prerequisite to make use of the SDF in the CI pipeline.
+Therefore in this timeframe, scenario processes are introduced only in
+a documentation way and as support for release management.
+
+Also the definition of generic scenarios can be done.
 
 
 
diff --git a/docs/scenario-lifecycle/scenario-overview.rst b/docs/scenario-lifecycle/scenario-overview.rst
index 9c9c508..4a7ff7a 100644
--- a/docs/scenario-lifecycle/scenario-overview.rst
+++ b/docs/scenario-lifecycle/scenario-overview.rst
@@ -14,77 +14,146 @@ Overview
 Problem Statement:
 ^^^^^^^^^^^^^^^^^^^
 
-OPNFV provides the NFV reference platform in different variants, using different
-upstream open source projects.
-In many cases this includes also different upstream projects providing similar or
-overlapping functionality.
+OPNFV provides the NFV reference platform in different variants, where
+each variant is called a "scenario".
 
-OPNFV introduces scenarios to define various combinations of components from upstream
-projects or configuration options for these components.
+OPNFV introduces scenarios in order to provide a way to deploy the stack
+using different combinations of upstream components, or to provide
+different sets of pre-defined configuration options for these
+components.
 
-The number of such scenarios has increased over time, so it is necessary to clearly
-define how to handle the scenarios.
+In some cases a scenario is introduced in order to provide isolation of
+a specific development effort from other ongoing development efforts,
+similar to the purpose of a branch in a code repository.
 
-Introduction:
+A certain amount of effort and resources is required in order to include
+a scenario in a release. The number of scenarios has increased over
+time, so it is necessary to identify ways to manage the number of
+scenarios and to avoid that their number grows infinitely. To enable
+this, we have to clearly define how to handle the lifecycle of
+scenarios, i.e. how to create, how to terminate, etc.
+
+
+Scenario types:
 ^^^^^^^^^^^^^^^^^^^
 Some OPNFV scenarios have an experimental nature, since they introduce
-new technologies that are not yet mature enough to provide a stable release.
-Nevertheless there also needs to be a way to provide the user with the
-opportunity to try these new features in an OPNFV release context.
+new technologies or features that are not yet mature or well integrated
+enough to provide a stable release. Nevertheless there also needs to be
+a way to provide the user with the opportunity to try these new features
+in an OPNFV release context.
 
 Other scenarios are used to provide stable environments for users
-that wish to build products or live deployments on them.
+desiring a certain combination of upstream components or interested in
+particular capabilities or use cases.
 
-OPNFV scenario lifecycle process will support this by defining two types of scenarios:
+The new OPNFV scenario lifecycle process proposed herein will support
+this by defining two types of scenarios:
 
 * **Generic scenarios** cover a stable set of common features provided
-  by different components and target long-term usage.
-* **Specific scenarios** are needed during development to introduce new upstream
-  components or new features.
-  They are intended to merge with other specific scenarios
-  and bring their features into at least one generic scenario.
-
-OPNFV scenarios are deployed using one of the installer tools.
-A scenario can be deployed by multiple installers and the result will look
-very similar but different. The capabilities provided by the deployments
-should be identical. Results of functional tests should be the same,
+by different components and target long-term usage and maintenance of
+the scenario. Only stable versions of upstream components are allowed to
+be deployed in a generic scenario. Across all generic scenarios in a
+given OPNFV release, the same version of a given upstream component
+should be deployed. Creation of generic scenarios and promotion of
+specific to generic scenario requires TSC approval, see section 5.
+Generic scenarios will get priority over specific scenarios in terms of
+maintenance effort and CI resources.
+
+* **Specific scenarios** are needed during development to introduce new
+upstream components or new features. They are typically derived from a
+generic scenario and are intended to bring their features back into the
+parent generic scenario once they are mature enough. It is also possible
+that multiple specific scenarios are merged before bringing them back to
+the parent scenario, for example in order to test and develop the
+integration of two specific features in isolation. Specific scenarios
+can consume unreleased upstream versions or apply midstream patches.
+Creation of specific scenarios is not gated, but if a project intends to
+release a specific scenario, it has to indicate that in its release plan
+at milestone MS1. The scenario itself can be created at any time, by
+means of a simple request by a PTL to the release manager.
+
+OPNFV scenarios are deployed using one of the OPNFV installer tools.
+Deploying a scenario will normally be supported by multiple installers.
+The capabilities provided by the resulting deployments should be
+identical. The set of tests to run and their results should be the same,
 independent of the installer that had been used. Performance or other
-behavioral aspects could be different.
-The scenario lifecycle process will also define how to document which installer
-can be used for a scenario and how the CI process can trigger automatic deployment
-for a scenario via one of the supported installers.
+behavioral aspects outside the scope of existing OPNFV tests could be
+different.
+
 
-When a developer decides to define a new scenario, he typically will take one
-of the existing scenarios and does some changes, such as:
+Parent-child and sibling relations:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When a developer decides to define a new scenario, he typically will
+take one of the existing scenarios and do some changes, such as:
 
 * add additional components
 * change a deploy-time configuration
-* use a component in a more experimental version
+* use a component in a more experimental version or with midstream
+patches applied
+
+In this case the already existing scenario is called a "parent" and the
+new scenario would be a "child".
+
+Typically parent scenarios are generic scenarios, but it is possible to
+derive from specific scenarios as well. it is expected that the child
+scenario develops its additions over some time up to a sufficient
+maturity, and then merges back to the parent. This way a continuous
+evolution of the generic scenarios as well as a manageable overall
+number of scenairos is ensured.
+
+In some cases a child scenario will diverge from its parent in a way
+that cannot easily be combined with the parent. Therefore, is is also
+possible to "promote" a scenario from specific to generic. If this is
+foreseeable upfront, the specific scenario can also be derived as a
+sibling rather that child.
+
+Promoting a scenario from specific to generic or creating a new generic
+scenario requires TSC approval. This document defines a process for
+this, see section 5.
 
-In this case the already existing scenario is called a "parent" and the new
-scenario a "child".
 
-Typically parent scenarios are generic scenarios, but this is not mandated.
-In most times the child scenario will develop the new functionality over some
-time and then try to merge its configuration back to the parent.
-But in other cases, the child will introduce a technology that cannot easily
-be combined with the parent.
-For this case this document will define how a new generic scenario can be created.
+Scenario deployment options:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Many OPNFV scenarios can be deployed in a HA (high availability) or non-HA
-configuration.
-HA configurations deploy some components according to a redundancy model,
-as the components support.
-In these cases multiple deployment options are defined for the same scenario.
+Many OPNFV scenarios can be deployed in different variants that do not
+justify creation of separate scenarios. An example would be HA (high
+availability) or non-HA configuration of otherwise identical scenarios.
+HA configurations deploy some components according to a redundancy
+model. Deployment options will also be used if the same scenario can be
+deployed on multiple types of hardware, i.e. Intel and ARM.
 
-Deployment options will also be used if the same scenario can be deployed
-on multiple types of hardware, i.e. Intel and ARM.
+In these cases multiple deployment options are defined for the same
+scenario. The set of distinguishable deployment option types (e.g.
+redundancy, processor architecture, etc.) will be pre-determined and
+each scenario will have to define at least one option for each option
+type.
+
+It is emphasized that virtual deployments vs. bare-metal deployments are
+intentionally not considered as deployment options. This should be a
+transparent feature of the installer based on the same scenario
+definition.
+
+For generic scenarios, there are certain expectations on the set of
+supported deployment options, e.g. a generic scenario should support at
+least an HA deployment and preferably both HA and non-HA.
+
+
+Scenario descriptor file:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Every scenario will be described in a scenario descriptor yaml file.
 This file shall contain all the necessary information for different users, such
 as the installers (which components to deploy etc.),
-the ci process (to find the right resources),
-the test projects (to select correct test cases), etc.
+the ci process (resource requirements in order to identify the right pod, machines, etc.).
+
+The scenario descriptor file will also document which installer
+can be used for a scenario and how the CI process can trigger automatic deployment
+for a scenario via one of the supported installers.
+
+
+MANO scenarios:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In early OPNFV releases, scenarios covered components of the infrastructure,
 that is NFVI and VIM.
diff --git a/docs/scenario-lifecycle/scenario-tree-danube.png b/docs/scenario-lifecycle/scenario-tree-danube.png
new file mode 100644
index 0000000..54c111e
--- /dev/null
+++ b/docs/scenario-lifecycle/scenario-tree-danube.png