Modifying the Pipelines section #414
Conversation
|
@mishaone, @rkratky I am done with the content changes, it would be great if you could review the changes, as I have reordered, renamed a few modules, deleted and merged a few Pipelines related modules. |
…creenshot changes.
|
@mishaone, and @rkratky please review. The changes to filenames and sequence can be seen in docs/topics/hello_world_developers.adoc in the PR. But, you will probably need to fork and clone if you want to see the logic behind the sequence changes. Basically, I have tried to keep the user flow related sections together and put the additional/optional information modules at the end. Probably the additional information sections make sense in a smaller usecase for pipelines/maybe the User guide. But the paring down is to be done as part of #406, after review, hence have left it there for now. |
Preeticp
changed the title
|
Builds and verifies fine. |
| @@ -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. | |||
There was a problem hiding this comment.
Do we need this addition in this step? It doesn't seem particularly useful to the step, just sort of marketing-speak-ish?
There was a problem hiding this comment.
Removing this for now, agree on the marketing-speak-ish observation, but more so for consistency. OTOH, in the creating application module, we are not explaining the why anywhere. Should this be rethought? Should we not have at least a line to explain the whys in the steps? We ask the user to do 1,2,3...without telling him why he needs to do them, and this is one of the primary areas of focus in OSIO.
| @@ -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>>. | |||
There was a problem hiding this comment.
The exact phrase again. Do we need it here? I suggest removing it in both places because it's just vague and not really telling us anything useful about this step where it's included.
There was a problem hiding this comment.
Exact phrase cause it is in the UG ifdef, whereas the previous one was for GS one. Basically I was trying to add a bit of context, but in this case probably not required since we have a link for more information.
| @@ -0,0 +1,14 @@ | |||
| [id="viewing_build_pipeline_logs"] | |||
There was a problem hiding this comment.
It's very difficult to judge what has changed when we move files, so I wonder if @rkratky's idea about a separate PR for changing file names (if there are any changes within the file) is something to follow in these cases.
There was a problem hiding this comment.
Sure, sounds like a good convention to follow from henceforth, meanwhile here is an attempt at trying to lessen the pain a bit:
Existing modules mapped to renamed ones:
about_stage_run.adoc > about_pipelines_stage_and_run.adoc
working_with_pipelines.adoc > reviewing_your_staged_application.adoc
approving_build_pipeline.adoc >approving_your_application.adoc
viewing_build_pipeline_oso.adoc > viewing_build_pipeline_logs.adoc
optional_detailed_views.adoc> viewing_application_deployment_details.adoc (Removed the internal Feature flag info as it is Beta, removed otional, as it has some important information relvant to developers and I wonder if we need to add a line or two about scaling pods up and down)
viewing_project_github.adoc > viewing_codebase_github.adoc
viewing_projects_oso>viewing_oso_projects
Earlier sequence of modules:
about_stage_run.adoc
working_with_pipelines.adoc
viewing_build_pipeline_oso.adoc
approving_build_pipeline.adoc
optional_detailed_views.adoc
viewing_project_github.adoc
viewing_projects_oso
Current Sequence of modules:
about_pipelines_stage_and_run.adoc
reviewing_your_staged_application.adoc
approving_your_application.adoc
viewing_build_pipeline_logs.adoc
viewing_application_deployment_details.adoc
viewing_codebase_github.adoc
viewing_oso_projects
Hope this helps.
| 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. |
There was a problem hiding this comment.
Probably my own fault, but there shouldn't be a "may" in our docs.
There was a problem hiding this comment.
Yep, may, could, were part of existing docs, but weeded them out now, thanks for pointing them out.
| @@ -0,0 +1,14 @@ | |||
| [id="viewing_build_pipeline_logs"] | |||
| = (Optional) Viewing the build pipeline logs | |||
There was a problem hiding this comment.
This has changed to optional but it's not meant to be. While the user waits, we definitely want them to go see the logs to get an idea of what's happening (and see how to access this information in their OSO account)
There was a problem hiding this comment.
Viewing the build pipeline logs is an optional section even in the original doc. I distinctly remember back in the demo days this was used to divert attention from the long wait time for a pipeline to go from one stage to another. I have tested this around 3 or 4 times now and the pipelines are executed fairly faster now.
This section is purely for troubleshooting (for advanced users) as the first paragraph clearly points out and imho we could safely add this to the User guide/ a detailed use case for pipelines section. This is definitely not something a user has to or should do as part of promoting his application. As to 'letting the user know what's happening' the UX has become fairly descriptive now, actually telling users what is happening, especially when the pipeline is first triggered. I actually liked that!
There was a problem hiding this comment.
IMO, it's useful to know where the logs are but if it's not a necessary part of the workflow anymore, we can just get rid of it, tbh. No need to clutter it up with more instructions that are useful.
| . 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. |
There was a problem hiding this comment.
This module is called approving your application but it talks about promoting your build more. Perhaps the name should be reassessed based on the content?
There was a problem hiding this comment.
AFAIU, we promote an application to production (in this case run) we do not promote a build. So it's either Promote your application or Approve your application. I picked the latter. But you are right, the word 'build' in a number of places needs to be replaced with application and could have created the perception. Taken care of now. Thanks for noticing.
|
|
||
| . 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. |
There was a problem hiding this comment.
I'd avoid using "roll out process". First, the language seems a bit informal to use, but also the UI still calls it "rollout" rather than roll out.
| [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. |
There was a problem hiding this comment.
I'm not sure I'm reading this correctly, but it sounds like the pipeline is somehow the subject of this part. Does "It" refer to the pipeline? I'm not sure the pipeline itself is doing anything, it's just a pipeline type that the application uses to deploy to stage or run. Can we reword this to reflect this?
There was a problem hiding this comment.
So far whatever I have read and understood from my discussions with Devs seems to suggest that the Pipeline triggers/pushes these actions.
Some examples:
Openshift docs: https://docs.openshift.com/container-platform/3.9/dev_guide/dev_tutorials/openshift_pipeline.html#overview
"This example demonstrates how to create an OpenShift Pipeline that will build, deploy, and verify a Node.js/MongoDB application using the nodejs-mongodb.json template."
Our UG docs (not authored by me): https://docs.openshift.io/user-guide.html#selecting_a_pipeline_type, Point #1 (On a totally tangential thought, wonder why this is a numbered list?): "It provides an end to end pipeline that moves your application through all the stages of application development, that is, build your source code, test your changes, rollout to the Stage environment, review, manually approve, and promote the changes to the Run environment."
I am not sure I understand your second last sentence, are you suggesting the application is the actor here?
But yet, here's an attempt at rewording it:
When you create a new codebase, the selected pipeline pushes version 1.0.1 of your new application into the Stage environment, and then awaits your approval to deploy into the Run environment.
Please note, this was already existing in the docs>Section 5.6 just above the adominition at the end of the module.
There was a problem hiding this comment.
I see. That sounds really odd to me in non technical terms to have a pipeline be the actor but if it's intentional and accurate, sounds like a non issue.
|
|
||
| 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. |
There was a problem hiding this comment.
The second sentence here again suggests that the pipeline is the actor. I don't think the pipeline itself is doing anything, AFAIK.
Also, could should not be mentioned in docs as well. Anything that indicates uncertainty should not be there, such as "may", "should", "could", "would", etc.
There was a problem hiding this comment.
How about this?
When you create a new codebase, the selected pipeline is triggered. In the Build Release stage of the pipeline, the build server is set, the build is started and then released.
+1, weeded out the "may" and "could", mercifully did not find any should or would :)
|
@mishaone I have addressed most of your comments, and replied to a few, if you let me know your thoughts about the same, I will update it accordingly and push the changes. Thank you! |
|
Looks good @Preeticp |
|
Fixed all review comments, builds and verifies fine. Thanks Misha. Merging it. |
This PR modifies, renames, deletes and merges modules to streamline the pipelines section. I have tried to order the modules in a way that is least disruptive for the user, as in if she is in the Pipelines view, the next module is from the same view, if she is in OSO then the next module is in OSO.
To Do: Update Screenshots