Porting guide for version 3 (#592)

Fixes: #561 

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

docs/definition.rst

@@ -88,6 +88,8 @@ Configuration options
 
 You may use the configuration YAML keys listed here in your v3 execution environment definition file.
 
+.. _additional_build_files:
+
 additional_build_files
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -111,6 +113,8 @@ Each list item must be a dictionary containing the following (non-optional) keys
       This may not be an absolute path or contain ``..`` within the path. This directory
       will be created for you if it does not exist.
 
+.. _additional_build_steps:
+
 additional_build_steps
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -179,6 +183,8 @@ build instruction file, so they will persist if you run your container build man
 
 If you specify the same variable in the execution environment definition and at the command line with the CLI :ref:`build-arg` flag, the CLI value will take higher precedence (the CLI value will override the value in the execution environment definition).
 
+.. _dependencies:
+
 dependencies
 ^^^^^^^^^^^^
 
@@ -237,7 +243,7 @@ The following keys are valid for this section:
       The system packages to be installed, in bindep format. This may either
       be a filename, or a list of requirements (see below for an example).
 
-The following example uses filenames that contain the various dependencies:
+The following example uses filenames that contain various dependencies:
 
 .. code:: yaml
 
@@ -275,6 +281,7 @@ And this example uses inline values:
             package_system: "python310"
             python_path: "/usr/bin/python3.10"
 
+.. _images:
 
 images
 ^^^^^^
@@ -289,6 +296,8 @@ Valid keys for this section are:
       key if the image is mirrored within your repository, but signed with the original
       image's signature key.
 
+.. _image_verification:
+
 image verification
 """"""""""""""""""
 You can verify signed container images if you are using the ``podman`` container
@@ -310,6 +319,8 @@ file for container image signature validation.
     :ref:`context directory <context>` that will be used during the build to
     validate the images.
 
+.. _options:
+
 options
 ^^^^^^^
 
@@ -393,6 +404,8 @@ Example ``options`` section:
         tags:
           - ee_development:latest
 
+.. _version:
+
 version
 ^^^^^^^
 

docs/index.rst

@@ -109,6 +109,7 @@ Collection maintainers can learn to correctly declare dependencies for their col
    definition
    usage
    collection_metadata
+   porting_guide_v3
    glossary
 
 .. toctree::

docs/porting_guide_v3.rst

@@ -0,0 +1,113 @@
+.. _porting_guide_v3:
+
+Ansible Builder version 3 Porting Guide
+=======================================
+
+This section discusses the behavioral changes between ``ansible-builder`` version 1.2 and version 3.0.
+
+We suggest you read this page along with `ansible-builder 3.0 release notes <https://github.com/ansible/ansible-builder/releases/tag/3.0.0>`_ to understand what updates you may need to make.
+
+.. contents:: Topics
+
+Overview
+--------
+The Ansible Builder 3.x execution environment definition file accepts seven top-level sections:
+
+* additional_build_files
+* additional_build_steps
+* build_arg_defaults
+* dependencies
+* images
+* options
+* version
+
+Porting options
+---------------
+
+You need to change the configuration YAML keys in your older (v1 and v2) execution environment file to the one listed here.
+
+additional_build_files
+^^^^^^^^^^^^^^^^^^^^^^
+
+This is a new configuration that can be used to specify files to be added to the build context directory.
+These can then be referenced or copied by `additional_build_steps` during any build stage.
+
+See the :ref:`additional_build_files <additional_build_files>` section for more details.
+
+additional_build_steps
+^^^^^^^^^^^^^^^^^^^^^^
+
+With Ansible Builder 3, you can specify more fine-grained build steps or custom commands for any build phase.
+These commands will be inserted directly into the build instruction file for the
+container runtime (For example, `Containerfile` or `Dockerfile`). The commands must conform to any rules required by the containerization tool.
+
+These are additional build steps -
+
+* ``prepend_base``
+* ``append_base``
+* ``prepend_galaxy``
+* ``append_galaxy``
+* ``prepend_builder``
+* ``append_builder``
+* ``prepend_final``
+* ``append_final``
+
+See the :ref:`additional_build_steps <additional_build_steps>` section for more details.
+
+dependencies
+^^^^^^^^^^^^
+
+Specifies dependencies to install into the final image, including ``ansible-core``, ``ansible-runner``, Python packages, system packages, and Ansible Collections. Ansible Builder automatically installs dependencies for any Ansible Collections you install.
+
+In general, you can use standard syntax to constrain package versions. Use the same syntax you would pass to ``dnf``, ``pip``, ``ansible-galaxy``, or any other package management utility. You can also define your packages or collections in separate files and reference those files in the ``dependencies`` section of your execution environment definition file.
+
+The following keys are valid for this section:
+
+* ``ansible_core``
+* ``ansible_runner``
+* ``galaxy``
+* ``python``
+* ``python_interpreter``
+* ``system``
+
+See the :ref:`dependencies <dependencies>` section for more details.
+
+images
+^^^^^^
+
+Specifies the base image to be used. At a minimum you *MUST* specify a source, image, and tag for the base image. The base image provides the operating system and may also provide some packages. We recommend using the standard ``host/namespace/container:tag`` syntax to specify images.
+
+See the :ref:`images <images>` section for more details.
+
+image verification
+""""""""""""""""""
+You can verify signed container images if you are using the ``podman`` container
+runtime.
+
+See the :ref:`image verification <image_verification>` section for more details.
+
+options
+^^^^^^^
+
+A dictionary of keywords/options that can affect
+builder runtime functionality. Valid keys for this section are:
+
+* ``container_init``
+* ``cmd``
+* ``entrypoint``
+* ``package_pip``
+* ``package_manager_path``
+* ``skip_ansible_check``
+* ``relax_passwd_permissions``
+* ``workdir``
+* ``user``
+* ``tags``
+
+See the :ref:`options <options>` section for more details.
+
+version
+^^^^^^^
+
+Must be ``3`` if you are using Ansible Builder 3.x.
+
+See the :ref:`version <version>` section for more details.