Note: This is a beta release of Red Hat Bugzilla 5.0. The data contained within is a snapshot of the live data so any changes you make will not be reflected in the production Bugzilla. Also email is disabled so feel free to test any aspect of the site that you want. File any problems you find or give feedback here.
Bug 1355596 - [DOCS] Document Developer Preview restrictions on build strategy
Summary: [DOCS] Document Developer Preview restrictions on build strategy
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: OpenShift Online
Classification: Red Hat
Component: Documentation
Version: 3.x
Hardware: Unspecified
OS: Unspecified
medium
medium
Target Milestone: ---
: ---
Assignee: Alex Dellapenta
QA Contact: Xiaowei Li
Vikram Goyal
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2016-07-12 03:04 UTC by Miciah Dashiel Butler Masters
Modified: 2017-05-05 21:01 UTC (History)
8 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2017-05-05 21:01:24 UTC
Target Upstream Version:


Attachments (Terms of Use)

Description Miciah Dashiel Butler Masters 2016-07-12 03:04:29 UTC
Document URL: 

https://github.com/openshift/openshift-docs/blob/master/dev_guide/builds.adoc


Section Number and Name: 

Pretty much the entire document.


Describe the issue: 

OpenShift Developer Preview permits only the source build strategy.  


Suggestions for improvement: 

We need to tell users that only the source build strategy is permitted, or remove references to other build strategies for OpenShift Developer Preview.

Additionally, we may want to tell users that inline Dockerfile definitions are not useful (they are intende for custom or Docker builds), or remove references to inline Dockerfile definitions for OpenShift Developer Preview.

There are many references to these unsupported features, and making all of these references conditional so that they can be elided from the Developer Preview documentation may be onerous and result in a messy, unmaintainable mass mired in a morass of ifdefs.  In order to avert ifdef nightmares, we may prefer instead to add a note up front that these features are disabled in Developer Preview.  Otherwise, if we want a cleaner end product, following is a list of changes we would want to make.  If this list is not too onerous, I can provide a pull request—please let me know if this is desired.

In the "Overview" section, we have the statement, "There are three build strategies:", followed by a list of build strategies.  We should indicate that there is only *one* permitted build strategy on Developer Preview, perhaps by changing the aforementioned statement to, "There is only one allowed build strategy," and listing only the source strategy after that statement.

In the "Overview" section, the phrase "It is up to each build strategy" could be changed to "It is up to the build strategy", which would work for both the case where we list only one build strategy and the case where we list three.

In the "Overview" section, the "Dockerfile" source type can be elided from the Developer Preview documentation, and the phrase "Dockerfile and Image can be used by themselves, with each other," can be changed to "Image can be used by itself".

The "BuildConfig Object Definition" example can be ifdeffed to provide a version without "dockerfile:" for Developer Preview, and footnote 4 of the example should list only "Source" as a valid strategy.

In the "Source-to-Image Strategy Options" section, the statement, "The following options are specific to the S2I build strategy" could be changed to replace the phrase "are specific" with the word "apply" in order to make the statement read well for both the case where we list only one build strategy and the case where we list three.

The entire "Docker Strategy Options" and "Custom Strategy Options" sections (i.e., everything from "Docker Strategy Options" up to "Build Inputs") can be elided from the Developer Preview documentation.

In list of inputs in the "Build Inputs" section, the "Inline Dockerfile definitions" list item can be elided from the Developer Preview documentation, as can references to the Dockerfile and custom builder in the following two paragraphs.  The example definition can be ifdeffed to remove the "dockerfile" stanza and associated footnote for Developer Preview.

In the "Git Repository Source Options" section, references to the Dockerfile can be elided, and the example can be ifdeffed to remove the "dockerfile" stanza" and associated footnote, for Developer Preview.

The "Dockerfile Source" section can be elided from the Developer Preview documentation.

In the "Binary Source" section, references to dockerfile in two paragraphs can be elided from the Developer Preview documentation.

In the "Image Source" section, the note about "Custom Strategy" can be elided from the Developer Preview documentation.

In the "Defining Secrets in the BuildConfig" section, the following note can be elided from the Developer Preview documentation: "Note that for a Docker strategy the destination directory must be a relative path."

The "Docker Strategy" and "Custom Strategy" sections can be elided from the Developer Preview documentation.

References to "Dockerfile" can be deleted from the "Starting a Build" section ("or a Dockerfile for a build")

In the "Canceling a Build" section, the reference to the Docker build strategy in the following statement can be elided from the Developer Preview documentation: "If the build uses the Docker or Source strategy, it will also include information about the source revision used for the build: commit ID, author, committer, and message."

In the "Accessing Build Logs" section, the reference to the Docker build strategy in the following statement can be elided from the Developer Preview documentation: "To enable more verbose output, pass the BUILD_LOGLEVEL environment variable as part of the sourceStrategy or dockerStrategy in a BuildConfig:".

In the "Image Change Triggers" section, the following paragraph can be elided from the Developer Preview documentation: "In addition to setting the image field for all Strategy types, for custom builds, the OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE environment variable is checked. If it does not exist, then it is created with the immutable image reference. If it does exist then it is updated with the immutable image reference."

In the "Using Docker Credentials for Pushing and Pulling Images" section, the following note can be elided from the Developer Preview documentation: "This example uses pullSecret in a Source build, but it is also applicable in Docker and Custom builds."

In the "Output Image Environment Variables" and "Output Image Labels" sections, the phrase "Docker and Source" can be replaced with just "Source" in the Developer Preview documentation.

In the "Using External Artifacts During a Build" documentation, the paragraph and example for the Docker build strategy, the reference to Dockerfile in the paragraph after the example, and the qualifier "only for a Source build strategy" can be elided from the Developer Preview documentation.


Additional information: 

The restriction on build strategies is expected apply to OpenShift Online as well.

Comment 1 Robert Stone 2016-10-04 20:44:46 UTC
Just ran into this when attempting to install the golang-ex sample application. Didn't find anything mentioning this until I searched Bugzilla.

Also see https://github.com/openshift/golang-ex/issues/17

Comment 2 Abhishek Gupta 2016-10-13 22:44:39 UTC
Is something holding this up?

Comment 3 Allison Heslin 2016-11-15 15:21:22 UTC
We are currently working on some documentation improvements to this section of the Developer Guide and will incorporate your feedback as part of those improvements.

Comment 8 Alex Dellapenta 2017-05-05 21:01:24 UTC
Since this BZ was opened, the single builds.adoc file got broken up into multiple files under the builds/ directory. I've gone through each of the items in the Description again and they've all since been addressed by the following 3 PRs:

https://github.com/openshift/openshift-docs/pull/4278
https://github.com/openshift/openshift-docs/pull/4330
https://github.com/openshift/openshift-docs/pull/4356

These changes are reflected in the published Online docs:

https://docs.openshift.com/online/dev_guide/builds/

I'm going to close this CURRENTRELEASE but please re-open if any more instances or related problems are found.


Note You need to log in before you can comment on or make changes to this bug.