WIP Update README.rst (#82)

* Update README.rst

s/future/past tense/g


1) mention ACD as that term has been used, though make it clear that's not a term we should be using anymore
2) Make it clear about packages (reference ansible-build-data/blob/master/2.10/acd.in)
3) for ansible-base definition, make it clear you may want to use that along side specific collections
4) Update links to pre-release builds of `ansible` Python package
5) Maybe mention antsibull

* Apply suggestions from code review

Co-authored-by: James Cassell <code@james.cassell.me>

* more

* Update README.rst

Co-authored-by: James Cassell <code@james.cassell.me>
Co-authored-by: Felix Fontein <felix@fontein.de>

README.rst

@@ -24,58 +24,61 @@ See the `Ansible Communication channels <https://docs.ansible.com/ansible/latest
 Where we've come from, and where we are going
 =============================================
 
-To understand where we are going, it's often useful to remind ourselves of where we are today.
+To understand where we are going, it's often useful to remind ourselves of where we came from.
 
-Ansible 2.9 and earlier
-------------------------
+Previously: Ansible 2.9 and earlier
+-----------------------------------
 
 **Classic Ansible**
 
 * Single repository `ansible/ansible <https://github.com/ansible/ansible>`_.
 * Single package called `ansible`
-* `ansible` has major releases twice a year
+* `ansible` had major releases twice a year
 * New features go into the next major release - ie worst case you need to wait 6 months
 
 
-Ansible 2.10 and later
-----------------------
+Now: Ansible 2.10 and later
+---------------------------
 
-* The ``ansible/ansible`` repository will only contain:
+* The ``ansible/ansible`` (`ansible-base`) repository only contains:
 
-  * The core Ansible programs, ``ansible-{playbook,galaxy,doc,test}``, etc.
-  * Documentation
+  * The core Ansible programs, ``ansible-{playbook,galaxy,doc,test,etc}``
+  * Some documentation
   * A tiny subset of modules and plugins to allow for a functioning controller
   * Together this will be known as ``ansible-base``
-* The rest of the modules and plugins will move into multiple Collections
-* Collections:
+* The rest of the modules and plugins have been moved into various "collections"
+
+  * Ansible Collections:
 
-  * Can be released independently of Ansible, at whatever release cycle/cadence the collection maintainer prefers.
-  * Will have their own repo (GitHub, GitLab, etc) with dedicated backlog, ie no more shared massive issue & PR backlog
-  * Should still have CI testing and in many cases can be tested more thoroughly
+    * Can be released independently of ansible-base and Ansible, at whatever release cycle/cadence the collection maintainer prefers.
+    * Will have their own repo (GitHub, GitLab, etc) with dedicated backlog, ie no more shared massive issue & PR backlog
+    * Should still have CI testing and in many cases can be tested more thoroughly
 
 * The released package of Ansible 2.10 will pull in ``ansible-base`` and the various community collections that were previously a part of ``ansible/ansible``
 
+The ``ansible`` package (will contain a subset of collections) and depend on the new ``ansible-base`` package (the Ansible engine).
 
 Terminology
 ===========
 
 
 Classic Ansible (CA)
-  What we think of as Ansible prior to 2020. The open source project and the deliverable. What you currently get (as of Ansible 2.9) when you type ``pip install ansible``. Currently developed almost entirely within the ``ansible/ansible`` repository on GitHub.
+  What we think of as Ansible prior to 2020. The open source project and the deliverable. What you currently get (as of Ansible 2.9 and earlier versions) when you type ``pip install ansible``. Was developed almost entirely within the ``ansible/ansible`` repository on GitHub.
 
 Collection
   A packaging format for bundling and distributing Ansible content: plugins, roles, modules. Can be released independent of other collections or ``ansible-base`` so features can be made available sooner to users. Installed via ``ansible-galaxy collection install <namespace.collection>``.
 
-Ansible Base
-  The codebase that will be contained in github.com/ansible/ansible for the Ansible 2.10 release. Contains a minimal amount of modules and plugins, allows other collections to be installed. Similar to Ansible 2.9 though without any content that has since moved into a collection. The devel branch of ``ansible/ansible`` is now ansible-base.
 
-There will be an ``ansible-base`` package (ie a RPM/Python/Deb package with only the minimal set of modules and plugins).
+``ansible`` (the package)
+  A replacement software package (Python, deb, rpm, etc) which contains a select group of Collections. It contains the collections to ensure that Ansible 2.9 playbooks don't require any extra collections to be be installed. This list of what's included can be found at `ansible-build-data <https://github.com/ansible-community/ansible-build-data/tree/master/2.10>`_. Will depend on the ``ansible-base`` package. Was previously refered to as ``ACD`` (Ansible Community Distribution).
 
-Ansible Community Content Collections
-  The collections which host the modules and plugins, previously in Ansible 2.9, which are managed by the community. These collections will be combined and released when you do ``$package_manager install ansible``. These may run at different cadences, and may now be installed individually by users via Ansible Galaxy.
+ ``ansible-base``
+  New for 2.10. The codebase that is now contained in github.com/ansible/ansible for the Ansible 2.10 release. It contains a minimal amount of modules and plugins and allows other collections to be installed. Similar to Ansible 2.9 though without any content that has since moved into a collection. The devel branch of ``ansible/ansible`` is now ansible-base.
+
+There will be an ``ansible-base`` package (RPM/Python/Deb package)with only the minimal set of modules and plugins).
 
 Ansible Galaxy
-  An online hub for finding and sharing Ansible community content.  Also, the command-line utility that lets users  install individual Ansible Collections. `galaxy.ansible.com <https://galaxy.ansible.com/>`_.
+  An online hub for finding and sharing Ansible community content.  Also, the command-line utility that lets users install individual Ansible Collections, ``ansible-galaxy install community.crypto``. `galaxy.ansible.com <https://galaxy.ansible.com/>`_.
 
 Fully Qualified Collection Name (FQCN)
   The full definition of a module, plugin, or role hosted within a collection, in the form ``namespace.collection.content_name``. Allows a Playbook to refer to a specific module or plugin from a specific source in an unambiguous manner, for example, ``community.grafana.grafana_dashboard``. The FQCN is required when you want to specify the exact source of a module and multiple modules with the same name are available. Can always be identified in a playbook; ideally not necessary in most playbooks, but in cases in which users have multiple collections installed with similar content, the FQCN will always be the explicit and authoritative indicator of which collection to use for content. Example: ``cisco.ios.ios_config`` would be the FQCN, and the playbook would generally call "ios_config" when this is required.
@@ -86,8 +89,11 @@ Namespace
 Collection name
   In the second part of a Fully Qualified Collection Name, the collection name further divides the functional characteristics of the collection content and denotes ownership.  For example, the cisco namespace might contain  ``cisco.ios``, ``cisco.ios_community``, and ``cisco.ios_prc``, containing content for managing ios network devices maintained by Cisco.
 
-The community.general collection
-  A special collection managed by the Ansible Community Team containing all the modules and plugins which shipped in Ansible 2.9 that don't have their own dedicated Collection. A work in progress can be found in `community.general <https://github.com/ansible-collection-migration/community.general/>`_ repository. At least initially there are no Long Term Support (LTS) plans, though we will see how the need for that grows over time.
+community.general (collection)
+  A special collection managed by the Ansible Community Team containing all the modules and plugins which shipped in Ansible 2.9 that don't have their own dedicated Collection. See community.general on `Galaxy <https://galaxy.ansible.com/community/general>`_ or it's `GitHub repository <https://github.com/ansible-collection/community.general/>`_ .
+
+community.network (collection)
+  Similar to ``community.general``, though focusing on Network modules. See community.network on `Galaxy <https://galaxy.ansible.com/community/network>`_ or it's `GitHub repository <https://github.com/ansible-collection/community.network/>`_ .
 
 Repository
   The location of the source code included in a collection. Contributors make suggestions, fix bugs, and add features through the repository. Collection owners can host repositories on GitHub, Gerrit, or any other source code repository platform they choose.
@@ -105,7 +111,7 @@ Work needed
 
 Ansible 2.9 already contains basic support for Collections.
 
-The majority of the Ansible 2.10 release cycle is for:
+The majority of the ansible-base 2.10 release cycle is for:
 
 * Defining what the split of collections should be
 * Defining which modules and plugins go into these new collections
@@ -114,24 +120,12 @@ The majority of the Ansible 2.10 release cycle is for:
 * Testing the changes
 * Getting feedback from *you*
 
-We will soon begin the migration of content out of ansible/ansible, into its new component collection repositories.
 
 Timeline
 --------
 
-**Warning:** Dates subject to change
-
-* **DONE** 2nd March 2020, we will freeze the devel branch using protected branches, and we will create the temp-2.10-devel branch from devel. This date marks the end of merging non-base plugin/module PRs into ansible/ansible.
-
-* **DONE** 9th March 2020, we will perform the initial migration against temp-2.10-devel, and we will do our initial testing of the components.
-
-* **DONE** 23rd March 2020, we intend to unfreeze devel and merge temp-2.10-devel back into devel. From that point on, devel for ansible/ansible will be for the ansible-base project only.
-
-* TBC, ``community.general`` accepts new Pull Requests (PRs).
-
-* TBC, the ``ansible`` package has been updated to include the Community Collections.
-
-* See `ROADMAP_2.10 <https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/roadmap/ROADMAP_2_10.rst>`_ for dates of  beta, RC, Release dates for ansible-base 2.10
+* See `status.rst <https://github.com/ansible-collections/overview/blob/master/status.rst>`_ for dates of  beta, RC, Release dates for ``ansible 2.10``
+* See `ROADMAP_2.10 <https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/roadmap/ROADMAP_2_10.rst>`_ for dates of  beta, RC, Release dates for ``ansible-base 2.10``
 
 FAQ
 ====
@@ -144,7 +138,7 @@ Users of Ansible
 Q: Once the next version of Ansible is released, will my playbooks still work
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-For users of the community version of ansible pip/apt-get install ansible will continue to give you a working install of Ansible including the three thousand plus modules.
+For users of the community version of ansible ``pip/apt-get install ansible`` will continue to give you a working install of Ansible including the three thousand plus modules that previously shipped with Ansible 2.9.
 
 Q: I deploy Ansible directly from devel. Is that still advised?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -159,8 +153,9 @@ These changes, however, will have both a temporary and permanent impact.
   * We cannot guarantee that devel will be as stable as it has been in the past during this transition period.
 * Permanent
 
-  * Users of devel will need to get both ansible (program) and the ansible collections that their playbooks rely on. The collections will reside in multiple other git repositories (or can be installed from galaxy).
-  * If your workflow presently updates your checkout of the ansible devel branch, you'll need to change it to also retrieve the collections you need otherwise your playbooks will fail once we migrate the contents. More information about what collections modules and plugins are migrating to to come.
+
+* Users of devel will need to get both ansible-base (the package with contains ``ansible-playbook``) and the ansible collections that their playbooks rely on. The collections will reside in multiple other git repositories (or can be installed from galaxy).
+  * If your workflow presently updates your checkout of the ansible devel branch, you'll need to change it to also retrieve the collections you need otherwise your playbooks will fail,
 
 Q: When will the next version of Ansible be released with these changes?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -181,12 +176,12 @@ Individual collections can be installed by doing:
 Q: What exactly is ansible-base for and what does it contain
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-**Ansible-base** is the name for what github.com/ansible/ansible has become now that most of the content has been removed.
+**Ansible-base** is the name of the code and package for what github.com/ansible/ansible has become now that most of the content has been removed.
 
 use-cases for ansible-base
 """"""""""""""""""""""""""
 
- ``ansible[|-playbook|-galaxy|-pull|-doc|-test]`` --help
+* ``ansible[|-playbook|-galaxy|-pull|-doc|-test]`` --help
 * Being able to install content from Galaxy or Automation Hub
 
   * ``ansible-galaxy collection ...``
@@ -197,11 +192,11 @@ use-cases for ansible-base
   * ie RHEL users will not use ``ansible-galaxy collection install ...``, they want RPMs
   * Ability to setup and use package repos
   * Ability to work online or offline
-  
+
 * Include things that are "hardcoded" into Ansible
 
   * eg ``stat`` is used to handle any file information internally
-  * ``include_tasks`` is hardcoded as the implementation is inside the engine, same with ``add_host``, ``group_by``, ``debug`` and others, async_wrapp, async-poll, assert/fail are 'parts of the language'  
+  * ``include_tasks`` is hardcoded as the implementation is inside the engine, same with ``add_host``, ``group_by``, ``debug`` and others, async_wrapp, async-poll, assert/fail are 'parts of the language'
 * Development
 
   * Ability to run ``ansible-test sanity,units,integration`` against the Ansible code base
@@ -217,25 +212,25 @@ Contributors to Ansible
 Q: I'd like to submit a new module or plugin to Ansible. How shall I proceed?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you're a vendor/partner and you're writing Ansible content to interact with your software, we recommend writing your own collection. This will allow you to pursue certification against the Ansible Automation Platform. For more info on certification, read here [FIXME: link].
+If you're a vendor/partner and you're writing Ansible content to interact with your software, we recommend writing your own collection. This will allow you to pursue certification against the Ansible Automation Platform. For more info on certification, read the `Partners Page <http://ansible.com/partners>`_.
 
-If you want to submit your module to the ``community.general`` Collection, please wait till this repo has been created (see timeline at the top of this document).
+If you want to submit your module to the ``community.general`` Collection, please wait till this repo has been created. FIXME, Possible direct to dedicated collection, otherwise fallback to c.general
 
-If you want to submit your module to an existing collection, you'll want to coordinate with the maintainers of those collections and follow their guidelines. Note that not all collections will necessarily accept new modules, nor follow the guidelines that ansible/ansible previously did.
+If you want to submit your module to an existing collection, you'll want to coordinate with the maintainers of those collections and follow their guidelines. 
 
-As of today **ansible-base (and ansible/ansible) will no longer accept new modules.**
+As of today **ansible-base (github.com/ansible/ansible) will no longer accept new modules.**
 
 Q: I'd like to submit a pull request to an existing Ansible module. How will I know where this module will live?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 We will have a `mapping <https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html#migrating-ansible-content-to-a-collection>`_ of old modules to their new homes. Should you submit a PR to the wrong repository, we will close it and point you to the correct repository.
 
-For new PRs please wait for the new Collections to be created.
+For new PRs please wait for the new Collections to be created. FIXME
 
 Q: I have existing pull requests to existing modules that will become part of the Ansible Community Collection. What will happen to those?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Pull requests merged before ``ansible/ansible:devel`` is frozen will end up in the new collections.
+FIXME Pull requests merged before ``ansible/ansible:devel`` is frozen will end up in the new collections.
 
 Pull requests not merged before the freeze, will need to be recreated in the corresponding new Collection Repo. We will have a tool to help move PRs from one repo to another.
 
@@ -268,7 +263,7 @@ Q: What will versioning and deprecation look like for Collections
 * In Collections
 
   * Can be versioned and released independently to Ansible
-  * MUST use `semver (Semantic Versioning) <https://semver.org/>`_
+  * By convention, Galaxy requires a Collection to follow `semver (Semantic Versioning) <https://semver.org/>`_
 
 Details around versioning and deprecation policy are still being worked on, we will have a proposal up shortly
 
@@ -300,10 +295,12 @@ This PR MUST add all the items removed by PR1.
 * ``tests/sanity/ignore-*.txt`` entries
 * ``meta/runtime.yml``
 
-**PR3:** Update ``ansible/ansible:devel`` branch entries for all files moved
+**PR3:** Update ``ansible/ansible:devel``
+
+For every module and plugin mentioned in PR1 and PR2:
 
 * ``lib/ansible/config/ansible_builtin_runtime.yml`` (redirect entry)
-* ``.github/BOTMETA.yml`` (migrated_to entry)
+* IGNORE: ``.github/BOTMETA.yml``, this isn't used anymore
 
 
 Q: How can I fix bugs in Ansible 2.9?