[skip-ci] clarify documentation on additional build commands file (#210)

Author: ddsharpe

site/create-image.md

@@ -53,7 +53,21 @@ Usage: imagetool create [OPTIONS]
 #### `--additionalBuildCommands`
 
 This is an advanced option that let's you provide additional commands to the Docker build step.  
-The input for this parameter is a simple text file that contains one or more of the valid sections: `before-jdk-install`, `after-jdk-install`, `before-fmw-install`, `after-fmw-install`, `before-wdt-command`, `after-wdt-command`, `final-build-commands`.
+The input for this parameter is a simple text file that contains one or more of the valid sections. Valid sections for create:
+
+| Section | Build Stage | Timing |
+| --- | --- | --- |
+| `before-jdk-install` | Intermediate (JDK_BUILD) | Before the JDK is installed. |
+| `after-jdk-install` | Intermediate (JDK_BUILD) | After the JDK is installed. |
+| `before-fmw-install` | Intermediate (WLS_BUILD) | Before the Oracle Home is created. |
+| `after-fmw-install` | Intermediate (WLS_BUILD) | After all of the Oracle middleware installers are finished. |
+| `before-wdt-command` | Intermediate (WDT_BUILD) | Before WDT is installed. |
+| `after-wdt-command` | Intermediate (WDT_BUILD) | After WDT domain creation/update is complete. |
+| `final-build-commands` | Final image | After all Image Tool actions are complete, and just before the Docker image is finalized. |
+
+NOTE: Changes made in intermediate stages may not be carried forward to the final image unless copied manually.  
+The Image Tool will copy the Java Home, Oracle Home, domain home, and WDT home directories to the final image.  
+Changes fully contained within these directories do not need an additional `COPY` command in the `final-build-commands` section.
 
 Each section can contain one or more valid Dockerfile commands and would look like the following:
 

site/rebase-image.md

@@ -44,8 +44,19 @@ Usage: imagetool rebase [OPTIONS]
 #### `--additionalBuildCommands`
 
 This is an advanced option that let's you provide additional commands to the Docker build step.  
-The input for this parameter is a simple text file that contains one or more of the valid sections: `before-jdk-install`, `after-jdk-install`, `before-fmw-install`, `after-fmw-install`, `before-wdt-command`, `after-wdt-command`, `final-build-commands`.
+The input for this parameter is a simple text file that contains one or more of the valid sections. Valid sections for rebase:
 
+| Section | Build Stage | Timing |
+| --- | --- | --- |
+| `before-jdk-install` | Intermediate (JDK_BUILD) | Before the JDK is installed. |
+| `after-jdk-install` | Intermediate (JDK_BUILD) | After the JDK is installed. |
+| `before-fmw-install` | Intermediate (WLS_BUILD) | Before the Oracle Home is created. |
+| `after-fmw-install` | Intermediate (WLS_BUILD) | After all of the Oracle middleware installers are finished. |
+| `final-build-commands` | Final image | After all Image Tool actions are complete, and just before the Docker image is finalized. |
+
+NOTE: Changes made in intermediate stages may not be carried forward to the final image unless copied manually.  
+The Image Tool will copy the Java Home and the Oracle Home directories to the final image.  
+Changes fully contained within these directories do not need an additional `COPY` command in the `final-build-commands` section.
 Each section can contain one or more valid Dockerfile commands and would look like the following:
 
 ```dockerfile

site/update-image.md

@@ -57,20 +57,24 @@ Update WebLogic Docker image with selected patches
 | `--wdtVersion` | WDT tool version to use.  |   |
 
 ## Additional information
-This section provides additional information for command-line parameters requiring more details or clarification.
 
 #### `--additionalBuildCommands`
 
 This is an advanced option that let's you provide additional commands to the Docker build step.  
-The input for this parameter is a simple text file that contains one or more of the valid sections: `before-jdk-install`, `after-jdk-install`, `before-fmw-install`, `after-fmw-install`, `before-wdt-command`, `after-wdt-command`, `final-build-commands`.
+The input for this parameter is a simple text file that contains one or more of the valid sections. Valid sections for update:
 
-Each section can contain one or more valid Dockerfile commands and would look like the following:
+| Section | Build Stage | Timing |
+| --- | --- | --- |
+| `before-wdt-command` | Intermediate (WDT_BUILD) | Before WDT is installed. |
+| `after-wdt-command` | Intermediate (WDT_BUILD) | After WDT domain creation/update is complete. |
+| `final-build-commands` | Final image | After all Image Tool actions are complete, and just before the Docker image is finalized. |
 
-#### `--latestPSU`
+NOTE: Changes made in intermediate stages may not be carried forward to the final image unless copied manually.  
+The Image Tool will copy the domain home and the WDT home directories to the final image.  
+Changes fully contained within these directories do not need an additional `COPY` command in the `final-build-commands` section.
 
-The `latestPSU` option will continue to be supported for the CREATE option, but has been deprecated for use in the 
-UPDATE option.  Because of the number of patches and their size, using `latestPSU` as an update to an existing image can 
-increase the size of the image significantly, and is not recommended. 
+
+Each section can contain one or more valid Dockerfile commands and would look like the following:
 
 ```dockerfile
 [after-fmw-install]
@@ -98,6 +102,12 @@ installation or domain creation steps, use the `final-build-commands` section so
 final stage of the image build.  Or, if the file needs to change the Oracle Home prior to domain creation, use 
 the `after-fmw-install` or `before-wdt-command` sections.
 
+#### `--latestPSU`
+
+The `latestPSU` option will continue to be supported for the CREATE option, but has been deprecated for use in the 
+UPDATE option.  Because of the number of patches and their size, using `latestPSU` as an update to an existing image can 
+increase the size of the image significantly, and is not recommended. 
+
 #### Use an argument file
 
 You can save all arguments passed for the Image Tool in a file, then use the file as a parameter.