fabric8io · Preeticp · Sep 4, 2018 · Aug 24, 2018 · Aug 27, 2018 · Aug 29, 2018
diff --git a/docs/images/hello-world_deployments.png b/docs/images/hello-world_deployments.png
diff --git a/docs/images/hello-world_john.png b/docs/images/hello-world_john.png
diff --git a/docs/images/openshift_online_console.png b/docs/images/openshift_online_console.png
diff --git a/docs/images/openshift_online_deployments.png b/docs/images/openshift_online_deployments.png
diff --git a/docs/images/oso_projects.png b/docs/images/oso_projects.png
diff --git a/docs/images/pipeline_firstrun.png b/docs/images/pipeline_firstrun.png
diff --git a/docs/images/pipeline_jenkins.png b/docs/images/pipeline_jenkins.png
diff --git a/docs/images/proj_gh.png b/docs/images/proj_gh.png
diff --git a/docs/images/promote.png b/docs/images/promote.png
diff --git a/docs/images/rollout_to_run.png b/docs/images/rollout_to_run.png
diff --git a/docs/images/vertx_stage.png b/docs/images/vertx_stage.png
diff --git a/docs/topics/hello_world_developers.adoc b/docs/topics/hello_world_developers.adoc
@@ -9,19 +9,19 @@ include::modules/about_application_codebases.adoc[leveloffset=+1]
 
 include::modules/creating_new_application.adoc[leveloffset=+1]
 
-include::modules/about_stage_run.adoc[leveloffset=+1]
+include::modules/about_pipelines_stage_and_run.adoc[leveloffset=+1]
 
-include::modules/working_with_pipelines.adoc[leveloffset=+1]
+include::modules/reviewing_your_staged_application.adoc[leveloffset=+1]
 
-include::modules/viewing_build_pipeline_oso.adoc[leveloffset=+1]
+include::modules/approving_your_application.adoc[leveloffset=+1]
 
-include::modules/approving_build_pipeline.adoc[leveloffset=+1]
+include::modules/viewing_build_pipeline_logs.adoc[leveloffset=+1]
 
-include::modules/optional_detailed_views.adoc[leveloffset=+1]
+include::modules/viewing_codebase_github.adoc[leveloffset=+1]
 
-include::modules/viewing_project_github.adoc[leveloffset=+1]
+include::modules/viewing_application_deployment_details.adoc[leveloffset=+1]
 
-include::modules/viewing_projects_oso.adoc[leveloffset=+1]
+include::modules/viewing_oso_projects.adoc[leveloffset=+1]
 
 include::modules/about_workspaces.adoc[leveloffset=+1]
 

diff --git a/docs/topics/modules/about_pipelines.adoc b/docs/topics/modules/about_pipelines.adoc
@@ -3,4 +3,4 @@
 
 _Pipelines_ define how your application is deployed. Each pipeline has multiple stages with a varying set of capabilities. They are crucial to ensure a continuous delivery system that test and deploy the code at each step to provide feedback to the user. Examples of such steps are unit testing, performance, integration, and deployment. Each step of the pipeline implements a different level of testing and deployment tasks, provides results, and then passes the code on to the next step.
 
-In {osio}, you configure a pipeline build when creating or importing a project. The pipeline build is triggered when a collaborator commits a change to the code repository.
+In {osio}, you initiate a pipeline build when creating or importing a project. The pipeline build is triggered when a collaborator commits a change to the code repository.
diff --git a/docs/topics/modules/about_pipelines_stage_and_run.adoc b/docs/topics/modules/about_pipelines_stage_and_run.adoc
@@ -0,0 +1,11 @@
+[id="about_pipelines_stage_run"]
+= About pipelines and the stage and run environments
+
+When you create a codebase, a pipeline build is initiated. Pipelines are automated, continuous integration and deployment processes, powered by Jenkins, which define how your application is deployed.
+
+The free OpenShift Online Starter subscription, included with your {osio} subscription, provides two environments named _Stage_ and _Run_ to deploy your applications.
+
+Initially, the build pipeline deploys the application to _Stage_, which is accessible to stakeholders for review through a public URL provided by OpenShift Online. If approved and promoted, the pipeline deploys it to the _Run_ environment. This simulates the workflow of pushing an application to a staging environment and reviewing it, before promoting it to production.
+
+The _Run_ environment is similar to a production environment but is another staging area. The reason _Run_ is not named _Production_ is that the OpenShift Online Starter subscription does not support running production applications.
+//See link:https://www.openshift.com/pricing/index.html[purchasing an OpenShift Online Pro subscription] for information about support for running production applications.
diff --git a/docs/topics/modules/about_stage_run.adoc b/docs/topics/modules/about_stage_run.adoc
diff --git a/docs/topics/modules/approving_build_pipeline.adoc b/docs/topics/modules/approving_build_pipeline.adoc
diff --git a/docs/topics/modules/approving_your_application.adoc b/docs/topics/modules/approving_your_application.adoc
@@ -0,0 +1,14 @@
+[id="approving_your_application"]
+= Approving your application
+
+If the quickstart application in the _Stage_ environment runs as expected, approve your application and promote it to the _Run_ environment:
+
+. Return to the {osio} tab which displays the *Pipeline* view and click btn:[Input Required] at the *Approve* stage of the pipeline.
+
+. Click btn:[Promote] to promote the build from the _Stage_ environment to the _Run_ environment. The roll out process from _Stage_ to _Run_ requires a few minutes.
++
+image::promote.png[Promote build]
+. Optionally, as your build is promoted to _Run_, click *helloworldvertx* or *Build #1* to view the detailed progress of the pipeline or build in your OpenShift Online console, respectively.
+. When the *Pipeline* view in {osio} indicates that the project is available in the _Run_ environment, click the icon (image:rollout_icon.png[title="Rollout"]) next to *Rollout to Run* to view the application in a new tab.
++
+image::rollout_to_run.png[Rollout to Run]
diff --git a/docs/topics/modules/creating_new_application.adoc b/docs/topics/modules/creating_new_application.adoc
@@ -28,7 +28,7 @@ ifeval::["{context}" == "hello-world"]
 +
 image::choose_mission_runtime.png[Choose mission and runtime]
 +
-. In the *Select Pipeline* section, select the first option, then click the blue arrow to continue to the next step.
+. In the *Select Pipeline* section, select the first option, then click the blue arrow to continue to the next step. The {osio} pipelines create repeatable, incrementally improving processes that test and deploy the code from creation to execution.
 +
 image::select_pipeline.png[Select a pipeline]
 +
@@ -48,7 +48,7 @@ ifeval::["{context}" == "user-guide"]
 +
 image::choose_mission_runtime.png[Choose mission and runtime]
 +
-. In the *Select Pipeline* section, select the appropriate option, then click the blue arrow to continue to the next step. The first option is suggested for most use cases because it provides stages to test your changes for each pipeline build. For more information see <<working_with_pipelines>>.
+. In the *Select Pipeline* section, select the appropriate option, then click the blue arrow to continue to the next step. The {osio} pipelines create repeatable, incrementally improving processes that test and deploy the code from creation to execution. The first option is suggested for most use cases. For more information see <<working_with_pipelines>>.
 +
 image::select_pipeline.png[Select a pipeline]
 

diff --git a/docs/topics/modules/creating_new_space_and_vertx_quickstart_project.adoc b/docs/topics/modules/creating_new_space_and_vertx_quickstart_project.adoc
@@ -9,14 +9,14 @@ include::modules/creating_new_space.adoc[leveloffset=+1]
 
 include::modules/creating_new_project.adoc[leveloffset=+1]
 
-include::modules/working_with_pipelines.adoc[leveloffset=+1]
+include::modules/reviewing_your_staged_application.adoc[leveloffset=+1]
 
 include::modules/viewing_build_pipeline_oso.adoc[leveloffset=+1]
 
-include::modules/approving_build_pipeline.adoc[leveloffset=+1]
+include::modules/approving_your_application.adoc[leveloffset=+1]
 
 include::modules/optional_detailed_views.adoc[leveloffset=+1]
 
 include::modules/viewing_project_github.adoc[leveloffset=+1]
 
-include::modules/viewing_projects_oso.adoc[leveloffset=+1]
+include::modules/viewing_projects_oso.adoc[leveloffset=+1]
diff --git a/docs/topics/modules/next_steps.adoc b/docs/topics/modules/next_steps.adoc
@@ -8,7 +8,7 @@ If you followed the instructions in this document, you have now learned about {o
 * Create new projects using the quickstart wizards and test them. See <<hello_world_developers>> for a Vert.X project.
 //and <<spring_boot_quickstart_tutorial>> for a Spring Boot project.
 * Plan your work by creating work items and execute them using iterative development cycles. See <<planning_your_work>>.
-* Use the build pipelines to stage reviews in the *Stage* and *Run* environments. See <<working_with_pipelines>>.
+* Use the build pipelines to stage reviews in the *Stage* and *Run* environments. See <<reviewing_your_staged_application>> and <<approving_your_application>>.
 * Create Che workspaces to edit your project code and commit the changes to GitHub. See <<creating_che_workspace-hello-world>> and <<committing_pushing_changes_git-hello-world>>.
 * Optimize the memory usage for your projects to use your OpenShift Online resources more efficiently. See <<optimizing_memory_usage>>.
 // and <<reducing_project_memory_usage-spring-boot>>.

diff --git a/docs/topics/modules/optional_detailed_views.adoc b/docs/topics/modules/optional_detailed_views.adoc
@@ -1,7 +1,7 @@
 [id="optional_detailed_views"]
 = (Optional) Detailed views
 
-Optionally, you can see an experimental detailed *Deployments* view for the *Test*, <<about_stage_run,*Stage*, and *Run*>> environments. This view displays the environment deployments, pods, events, and other information.
+Optionally, you can see an experimental detailed *Deployments* view for the *Test*, <<about_pipelines_stage_run,*Stage*, and *Run*>> environments. This view displays the environment deployments, pods, events, and other information.
 
 View the details for the *Deployments* as follows:
 

diff --git a/docs/topics/modules/reviewing_your_staged_application.adoc b/docs/topics/modules/reviewing_your_staged_application.adoc
@@ -0,0 +1,26 @@
+[id="reviewing_your_staged_application"]
+= Reviewing your staged application
+
+When you create a new codebase, the selected pipeline builds your application. It pushes version 1.0.1 of your new application into the _Stage_ environment, and then awaits your approval to deploy into the _Run_ environment.
+
+<<about_pipelines_stage_run,_Stage_ and _Run_>> are individual OpenShift projects. _Stage_ is a production staging area to review and test changes before they are finalized and then staged on _Run_.
+
+To review your application on _Stage_:
+
+. At the top of the page, click *Create*, and then click *Pipelines* to see the build pipelines for your new application. The pipeline first sets your build server, starts the build, and releases the build. When the pipeline build pushes the application to stage, it displays at the *Approve* stage. This could take a few minutes.
++
+image::pipeline_firstrun.png[Pipeline First Run]
++
+NOTE: If your pipeline build does not start for more than ten minutes, you can manually start a pipeline build using the instructions at <<pipeline_build_failure>>.
+
+. Click the icon (image:rollout_icon.png[title="Rollout"]) next to *Rollout to Stage* in the displayed pipeline. OpenShift Online provides this public URL to access the staged quickstart application.
++
+A new browser tab displays the HTTP Booster application running on _Stage_. The Vert.x HTTP booster quickstart produces a simple API behind a REST endpoint over HTTP with a minimalist user interface.
++
+image::vertx_stage.png[Staged Application]
++
+NOTE: If the application does not load, see <<application_not_available>> for troubleshooting information.
+
+. To test the application, enter a name in the *Name* field and click btn:[Invoke]. The *Result* field displays the JSON result returning from the API.
++
+image::hello-world_john.png[Test the Application]
diff --git a/docs/topics/modules/viewing_application_deployment_details.adoc b/docs/topics/modules/viewing_application_deployment_details.adoc
@@ -0,0 +1,15 @@
+[id="viewing_application_deployment_details"]
+= Viewing your application deployment details
+
+You can see a detailed view of your application pods in the <<about_pipelines_stage_run,stage, and run>> environments, resources consumed in the two environments, and the overall resources used by the application in the *Deployments* view as follows:
+
+. At the top of the page, click *Create* and then click *Deployments* to see the deployment details.
+. In *Applications*, expand *helloworldvertx* to see the application pods and the resources consumed in the *stage* and *run* environments respectively. The *Resource Usage* at the bottom of the screen displays the overall resources used by your applications in {osio}.
++
+image::hello-world_deployments.png[Deployments page]
+. To see further deployment details in your OpenShift Online console, in either the *Stage* or *Run* environments, click the options (image:kabob.png[title="Options"]) icon and then click *View OpenShift Console*.
+
+. If prompted, click btn:[LOGIN WITH RED HAT] to log in to your OpenShift Online account. When logged in, the OpenShift Online console displays an overview of your application.
+. In the left pane, click *Applications* > *Deployments* to view details about the application deployment in the appropriate environment.
++
+image::openshift_online_deployments.png[OpenShift Online Deployments]
diff --git a/docs/topics/modules/viewing_build_pipeline_logs.adoc b/docs/topics/modules/viewing_build_pipeline_logs.adoc
@@ -0,0 +1,14 @@
+[id="viewing_build_pipeline_logs"]
+= (Optional) Viewing the build pipeline logs
+
+Optionally, while you wait for the pipeline build, you can view the build details in the Jenkins log. For experienced users, these logs are useful when troubleshooting problems with builds if required.
+
+. In the *Pipeline* page, click *View Log* for the build pipeline in progress.
+. When prompted, log into Jenkins with your OpenShift Online account. If the page does not display, you may need to wait for a few minutes for the Jenkins instance to initialize and try again.
+Once you are logged in, the page displays the logs for your pipeline build.
++
+image::pipeline_jenkins.png[Pipeline Build Logs in Jenkins]
++
+WARNING: Do not click the *Proceed* or *Abort* options at the end of the logs.
+
+You can now examine the log output to troubleshoot build problems if needed.
diff --git a/docs/topics/modules/viewing_build_pipeline_oso.adoc b/docs/topics/modules/viewing_build_pipeline_oso.adoc
diff --git a/docs/topics/modules/viewing_codebase_github.adoc b/docs/topics/modules/viewing_codebase_github.adoc
@@ -0,0 +1,11 @@
+[id="viewing_codebase_github"]
+= Viewing your codebase in GitHub
+
+After reviewing your pipeline build running in {osio} and OpenShift Online, view your application <<about_application_codebases,codebase>> in GitHub as follows:
+
+. Return to the *Pipeline* view in {osio}, the *Source Repository* provides the link to the codebase of your application. Right click the link and open it in a new tab to see your codebase in GitHub.
+. In the repository, click the *Jenkinsfile* to view details on staging and rolling out of the pipelines.
++
+image::proj_gh.png[Project Code in GitHub]
+
+Use the codebase link to review code commits and details in your GitHub repository.
diff --git a/.../topics/modules/viewing_projects_oso.adoc → .../topics/modules/viewing_oso_projects.adoc b/.../topics/modules/viewing_projects_oso.adoc → .../topics/modules/viewing_oso_projects.adoc
@@ -1,14 +1,14 @@
-[id="viewing_projects_oso"]
-= Viewing projects in OpenShift Online
+[id="viewing_oso_projects"]
+= Viewing your OpenShift Online projects
 
-To view the OpenShift Online projects that support the pipeline for your project, navigate to your link:https://console.starter-us-east-2.openshift.com/console/projects/[OpenShift Online Console].
+To view all the OpenShift Online projects that support your application, navigate to link:https://console.starter-us-east-2.openshift.com/console/projects/[*My Projects*] in the OpenShift Online Console.
 
 image::oso_projects.png[OpenShift Online Projects]
 
 This page displays the following projects and namespaces that are created in OpenShift Online:
 
 * The *_username_* project is where your pipelines run. Your OpenShift Online user name is the name of your project.
 * The *_username-che_* project represents your <<about_workspaces,Che Host and workspaces>>.
-* The *_username-jenkins_* project represents your Jenkins Master or your Jenkins Slaves. Click *Monitoring* after clicking this project to access your Jenkins console.
+* The *_username-jenkins_* project represents your Jenkins Master for your Jenkins Slaves. Click this project, and then click *Monitoring* in the left pane to access your Jenkins console.
 * The *_username-run_* project is identical to the *_username-stage_* project and is an environment for experimenting with your OpenShift pods and monitoring the memory usage for your application.
 * The *_username-stage_* project is for your personal use. Use this project to see the pods that are created when pipelines are triggered in {osio}. For maintenance, select this project and power down individual pods as required.
diff --git a/docs/topics/modules/viewing_project_github.adoc b/docs/topics/modules/viewing_project_github.adoc
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,4 +3,4 @@

		_Pipelines_ define how your application is deployed. Each pipeline has multiple stages with a varying set of capabilities. They are crucial to ensure a continuous delivery system that test and deploy the code at each step to provide feedback to the user. Examples of such steps are unit testing, performance, integration, and deployment. Each step of the pipeline implements a different level of testing and deployment tasks, provides results, and then passes the code on to the next step.

		In {osio}, you configure a pipeline build when creating or importing a project. The pipeline build is triggered when a collaborator commits a change to the code repository.
		In {osio}, you initiate a pipeline build when creating or importing a project. The pipeline build is triggered when a collaborator commits a change to the code repository.