From c6a29ed7d292d0e2901d512f0fb29b2947c298fd Mon Sep 17 00:00:00 2001
From: Sam Doran <sdoran@redhat.com>
Date: Mon, 24 Feb 2020 17:48:36 -0500
Subject: [PATCH] [stable-2.9] Update example requirements file docs (#67626)
 (#67714)

Use "name" when possible rather than "src" to make the examples
of roles and collections in a single requirements files more
coherenant. Fundamentally, roles and collections are completely different.
But we can make the requiremets file easier to read by unifying the
format as much as possible.
(cherry picked from commit 6c70959131)

Co-authored-by: Sam Doran <sdoran@redhat.com>
---
 docs/docsite/rst/galaxy/user_guide.rst        | 30 +++++++++----------
 .../installing_multiple_collections.txt       |  2 +-
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/docs/docsite/rst/galaxy/user_guide.rst b/docs/docsite/rst/galaxy/user_guide.rst
index ed3128a3d2c..5ef4744e07c 100644
--- a/docs/docsite/rst/galaxy/user_guide.rst
+++ b/docs/docsite/rst/galaxy/user_guide.rst
@@ -252,27 +252,27 @@ Use the following example as a guide for specifying roles in *requirements.yml*:
 .. code-block:: yaml
 
     # from galaxy
-    - src: yatesr.timezone
+    - name: yatesr.timezone
 
     # from GitHub
     - src: https://github.com/bennojoy/nginx
 
     # from GitHub, overriding the name and specifying a specific tag
-    - src: https://github.com/bennojoy/nginx
+    - name: nginx_role
+      src: https://github.com/bennojoy/nginx
       version: master
-      name: nginx_role
 
     # from a webserver, where the role is packaged in a tar.gz
-    - src: https://some.webserver.example.com/files/master.tar.gz
-      name: http-role-gz
+    - name: http-role-gz
+      src: https://some.webserver.example.com/files/master.tar.gz
 
     # from a webserver, where the role is packaged in a tar.bz2
-    - src: https://some.webserver.example.com/files/master.tar.bz2
-      name: http-role-bz2
+    - name: http-role-bz2
+      src: https://some.webserver.example.com/files/master.tar.bz2
 
     # from a webserver, where the role is packaged in a tar.xz (Python 3.x only)
-    - src: https://some.webserver.example.com/files/master.tar.xz
-      name: http-role-xz
+    - name: http-role-xz
+      src: https://some.webserver.example.com/files/master.tar.xz
 
     # from Bitbucket
     - src: git+https://bitbucket.org/willthames/git-ansible-galaxy
@@ -297,7 +297,7 @@ You can install roles and collections from the same requirements files, with som
     ---
     roles:
       # Install a role from Ansible Galaxy.
-      - src: geerlingguy.java
+      - name: geerlingguy.java
         version: 1.9.6
 
     collections:
@@ -333,7 +333,7 @@ The following shows the contents of the :file:`requirements.yml` file that now i
 .. code-block:: bash
 
   # from galaxy
-  - src: yatesr.timezone
+  - name: yatesr.timezone
   - include: <path_to_requirements>/webserver.yml
 
 To install all the roles from both files, pass the root file, in this case :file:`requirements.yml` on the
@@ -405,10 +405,10 @@ Alternately, you can specify the role dependencies in the complex form used in
 .. code-block:: yaml
 
     dependencies:
-      - src: geerlingguy.ansible
-      - src: git+https://github.com/geerlingguy/ansible-role-composer.git
+      - name: geerlingguy.ansible
+      - name: composer
+        src: git+https://github.com/geerlingguy/ansible-role-composer.git
         version: 775396299f2da1f519f0d8885022ca2d6ee80ee8
-        name: composer
 
 When dependencies are encountered by ``ansible-galaxy``, it will automatically install each dependency to the ``roles_path``. To understand how dependencies are handled during play execution, see :ref:`playbooks_reuse_roles`.
 
@@ -429,7 +429,7 @@ Use ``list`` to show the name and version of each role installed in the *roles_p
       - ansible-network.config_manager, v2.6.2
       - ansible-network.cisco_nxos, v2.7.1
       - ansible-network.vyos, v2.7.3
-    - ansible-network.cisco_ios, v2.7.0
+      - ansible-network.cisco_ios, v2.7.0
 
 Remove an installed role
 ------------------------
diff --git a/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt
index bd2d1a1e1c6..d6a8ffb91b1 100644
--- a/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt
+++ b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt
@@ -23,7 +23,7 @@ file used in older Ansible releases.
     ---
     roles:
       # Install a role from Ansible Galaxy.
-      - src: geerlingguy.java
+      - name: geerlingguy.java
         version: 1.9.6
 
     collections: