Docs porting guides 2.0 & 2.3 (ansible#27632)

* Create new "Porting Guide" section

Create new landing page
Add porting_guide_2.3

* correct CHANGELOG

* Document blocks

* Document named blocks

* OpenBSD & async action plugins

* OpenBSD & async action plugins

* versioadded for name

* review comments

CHANGELOG.md

@@ -282,9 +282,12 @@ Ansible Changes By Release
   * win_security_policy
   * win_wakeonlan
 
+<a id="2.3"></a>
 
 ## 2.3 "Ramble On" - 2017-04-12
 
+Moving to Ansible 2.3 guide http://docs.ansible.com/ansible/porting_guide_2.3.html
+
 ### Major Changes
 * Documented and renamed the previously released 'single var vaulting' feature, allowing user to use vault encryption for single variables in a normal YAML vars file.
 * Allow module_utils for custom modules to be placed in site-specific directories and shipped in roles
@@ -598,6 +601,7 @@ Ansible Changes By Release
   * zfs_facts
   * zpool_facts
 
+<a id="2.2.1"></a>
 
 ## 2.2.1 "The Battle of Evermore" - 2017-01-16
 
@@ -624,10 +628,11 @@ Ansible Changes By Release
 * Improvements and fixes to OpenBSD fact gathering.
 * Updated `make deb` to use pbuilder. Use `make local_deb` for the previous non-pbuilder build.
 * Fixed Windows async to avoid blocking due to handle inheritance.
-* Fixed bugs in the mount module on older Linux kernels and *BSDs
+* Fixed bugs in the mount module on older Linux kernels and BSDs
 * Various minor fixes for Python 3
 * Inserted some checks for jinja2-2.9, which can cause some issues with Ansible currently.
 
+<a id="2.2"></a>
 
 ## 2.2 "The Battle of Evermore" - 2016-11-01
 
@@ -942,12 +947,16 @@ Notice given that the following will be removed in Ansible 2.4:
   * nxos_template
   * ops_template
 
+<a id="2.1.4"></a>
+
 ## 2.1.4 "The Song Remains the Same" - 2017-01-16
 
 * Security fix for CVE-2016-9587 - An attacker with control over a client system being managed by Ansible and the ability to send facts back to the Ansible server could use this flaw to execute arbitrary code on the Ansible server as the user and group Ansible is running as.
 * Fixed a bug with conditionals in loops, where undefined variables and other errors will defer raising the error until the conditional has been evaluated.
 * Added a version check for jinja2-2.9, which does not fully work with Ansible currently.
 
+<a id="2.1.3"></a>
+
 ## 2.1.3 "The Song Remains the Same" - 2016-11-04
 
 * Security fix for CVE-2016-8628 - Command injection by compromised server via fact variables. In some situations, facts returned by modules could overwrite connection-based facts or some other special variables, leading to injected commands running on the Ansible controller as the user running Ansible (or via escalated permissions).
@@ -960,11 +969,13 @@ Notice given that the following will be removed in Ansible 2.4:
   login_password as no_log so the password is obscured when logging.
 * Fixed several bugs related to locating files relative to role/playbook directories.
 * Fixed a bug in the way hosts were tested for failed states, resulting in incorrectly skipped block sessions.
-* Fixed a bug in the way our custom JSON encoder is used for the to_json* filters.
+* Fixed a bug in the way our custom JSON encoder is used for the `to_json*` filters.
 * Fixed some bugs related to the use of non-ascii characters in become passwords.
 * Fixed a bug with Azure modules which may be using the latest rc6 library.
 * Backported some docker_common fixes.
 
+<a id="2.1.2"></a>
+
 ## 2.1.2 "The Song Remains the Same" - 2016-09-29
 
 ### Minor Changes
@@ -1027,6 +1038,8 @@ Module fixes:
   Use `_fixup_perms2` if support for previous releases is not required.
   Otherwise use `_fixup_perms` with `recursive=False`.
 
+<a id="2.1"></a>
+
 ## 2.1 "The Song Remains the Same"
 
 ### Major Changes:
@@ -1214,6 +1227,8 @@ Module fixes:
   completely in 2.3, after which time it will be an error.
 * play_hosts magic variable, use ansible_play_batch or ansible_play_hosts instead.
 
+<a id="2.0.2"></a>
+
 ## 2.0.2 "Over the Hills and Far Away"
 
 * Backport of the 2.1 feature to ensure per-item callbacks are sent as they occur,
@@ -1255,18 +1270,20 @@ Module fixes:
   permissions on the temporary file too leniently on a temporary file that was
   executed as a script.  Addresses CVE-2016-3096
 * Fix a bug in the uri module where setting headers via module params that
-  start with HEADER_ were causing a traceback.
+  start with `HEADER_` were causing a traceback.
 * Fix bug in the free strategy that was causing it to synchronize its workers
   after every task (making it a lot more like linear than it should have been).
 
+<a id="2.0.1"></a>
+
 ## 2.0.1 "Over the Hills and Far Away"
 
 * Fixes a major compatibility break in the synchronize module shipped with
   2.0.0.x.  That version of synchronize ran sudo on the controller prior to
   running rsync.  In 1.9.x and previous, sudo was run on the host that rsync
   connected to.  2.0.1 restores the 1.9.x behaviour.
 * Additionally, several other problems with where synchronize chose to run when
-  combined with delegate_to were fixed.  In particular, if a playbook targeted
+  combined with delegate_to were fixed.  In particular, if a playbook targetted
   localhost and then delegated_to a remote host the prior behavior (in 1.9.x
   and 2.0.0.x) was to copy files between the src and destination directories on
   the delegated host.  This has now been fixed to copy between localhost and
@@ -1300,6 +1317,8 @@ Module fixes:
   this might cause an error if settings environment on play depending on 'ansible_env'
   which was previouslly ignored
 
+<a id="2.0"></a>
+
 ## 2.0 "Over the Hills and Far Away" - Jan 12, 2016
 
 ### Major Changes:

docs/docsite/rst/index.rst

@@ -7,7 +7,7 @@ About Ansible
 Welcome to the Ansible documentation!
 
 Ansible is an IT automation tool.  It can configure systems, deploy software, and orchestrate more advanced IT tasks
-such as continuous deployments or zero downtime rolling updates.  
+such as continuous deployments or zero downtime rolling updates.
 
 Ansible's main goals are simplicity and ease-of-use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with an accelerated socket mode and pull modes as alternatives), and a language that is designed around auditability by humans--even those not familiar with the program.
 
@@ -16,7 +16,7 @@ We believe simplicity is relevant to all sizes of environments, so we design for
 Ansible manages machines in an agent-less manner. There is never a question of how to
 upgrade remote daemons or the problem of not being able to manage systems because daemons are uninstalled.  Because OpenSSH is one of the most peer-reviewed open source components, security exposure is greatly reduced. Ansible is decentralized--it relies on your existing OS credentials to control access to remote machines. If needed, Ansible can easily connect with Kerberos, LDAP, and other centralized authentication management systems.
 
-This documentation covers the current released version of Ansible (|version|) and also some development version features (|versiondev|).  For recent features, we note in each section the version of Ansible where the feature was added.  
+This documentation covers the current released version of Ansible (|version|) and also some development version features (|versiondev|).  For recent features, we note in each section the version of Ansible where the feature was added.
 
 Ansible, Inc. releases a new major release of Ansible approximately every two months.  The core application evolves somewhat conservatively, valuing simplicity in language design and setup. However, the community around new modules and plugins being developed and contributed moves very quickly, typically adding 20 or so new modules in each release.
 
@@ -40,6 +40,6 @@ Ansible, Inc. releases a new major release of Ansible approximately every two mo
    faq
    glossary
    YAMLSyntax
-   porting_guide_2.0
+   porting_guides
    python_3_support
    release_and_maintenance

docs/docsite/rst/playbooks_blocks.rst

@@ -9,20 +9,18 @@ by the tasks enclosed by a block. i.e. a `when` will be applied to the tasks, no
 
 
 .. code-block:: YAML
- :emphasize-lines: 2
+ :emphasize-lines: 3
  :caption: Block example
 
     tasks:
-      - block:
+      - name: Install Apache
+        block:
           - yum: name={{ item }} state=installed
             with_items:
               - httpd
               - memcached
-
           - template: src=templates/src.j2 dest=/etc/foo.conf
-
           - service: name=bar state=started enabled=True
-
         when: ansible_distribution == 'CentOS'
         become: true
         become_user: root
@@ -32,6 +30,9 @@ In the example above, each of the 3 tasks will be executed after appending the `
 and evaluating it in the task's context. Also they inherit the privilege escalation directives enabling "become to root"
 for all the enclosed tasks.
 
+. versionadded:: 2.3
+
+The `name:` keyword for `blocks:` was added in Ansible 2.3.
 
 .. _block_error_handling:
 
@@ -41,20 +42,21 @@ Error Handling
 Blocks also introduce the ability to handle errors in a way similar to exceptions in most programming languages.
 
 .. code-block:: YAML
- :emphasize-lines: 2,6,10
+ :emphasize-lines: 3,7,11
  :caption: Block error handling example
 
-  tasks:
-   - block:
-       - debug: msg='i execute normally'
-       - command: /bin/false
-       - debug: msg='i never execute, cause ERROR!'
-     rescue:
-       - debug: msg='I caught an error'
-       - command: /bin/false
-       - debug: msg='I also never execute :-('
-     always:
-       - debug: msg="this always executes"
+   tasks:
+    - name: Attempt and gracefull roll back demo
+      block:
+        - debug: msg='I execute normally'
+        - command: /bin/false
+        - debug: msg='I never execute, due to the above task failing'
+      rescue:
+        - debug: msg='I caught an error'
+        - command: /bin/false
+        - debug: msg='I also never execute :-('
+      always:
+        - debug: msg="this always executes"
 
 
 The tasks in the ``block`` would execute normally, if there is any error the ``rescue`` section would get executed
@@ -65,20 +67,21 @@ error did or did not occur in the ``block`` and ``rescue`` sections.
 Another example is how to run handlers after an error occurred :
 
 .. code-block:: YAML
- :emphasize-lines: 4,8
+ :emphasize-lines: 5,9
  :caption: Block run handlers in error handling
 
   tasks:
-   - block:
-       - debug: msg='i execute normally'
-         notify: run me even after an error
-       - command: /bin/false
-     rescue:
-       - name: make sure all handlers run
-         meta: flush_handlers
-  handlers:
-    - name: run me even after an error
-      debug: msg='this handler runs even on error'
+    - name: Attempt and gracefull roll back demo
+      block:
+        - debug: msg='I execute normally'
+          notify: run me even after an error
+        - command: /bin/false
+      rescue:
+        - name: make sure all handlers run
+          meta: flush_handlers
+   handlers:
+     - name: run me even after an error
+       debug: msg='this handler runs even on error'
 
 .. seealso::
 
@@ -93,4 +96,3 @@ Another example is how to run handlers after an error occurred :
 
 
 
-