Docs: Collections overview #3

gundalow · 2020-02-17T20:12:52Z

SUMMARY

Community docs for Collections.

My hope is every time someone asks a question a PRs is raised to update this document.

This isn't in the main docsite (docs.ansible.com) so we can iterate faster, especially between now and 2.10 being released.

Review welcome:

Is this clear
What other FAQ entries could be added

ISSUE TYPE

Docs Pull Request

README.rst

geerlingguy · 2020-02-17T21:06:55Z

README.rst

+  A packaging format for bundling and distributing Ansible content: plugins, roles, modules. Can be released independently to other collections or Ansible 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 only the 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. Only contains a small set of modules and plugins. A work in progress can be found in `ansible-base <https://github.com/ansible-collection-migration/ansible-base/>`_ repository.


s/Contains only the minimal amount/Contains a minimal amount of modules and plugins

Also can probably drop the 'Only contains a small set of modules and plugins.' line.

Will there be a pip package to install just ansible-base? E.g. pip install ansible-base? I can see many situations where it would be useful to get just base and not 'Community Content Collections'.

Will there be a pip package to install just ansible-base? E.g. pip install ansible-base? I can see many situations where it would be useful to get just base and not 'Community Content Collections'.

Yes, I can also see that being useful, though the exact packaging details of ansible (and optionally ansible-base) haven't been defined. I've made a note that we should get what we have written up and put somewhere public.

geerlingguy · 2020-02-17T21:14:31Z

README.rst

+
+**Warning:** Dates subject to change
+
+* On 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.


If possible, it would be nice to have a list of what are considered the 'base plugin/modules' and link to that list here.

Good call, I've added Q: What exactly is ansible-base for and what will it contain to the FAQ, detail the use-cases and linked to scenario & repo

README.rst

geerlingguy · 2020-02-17T21:16:43Z

README.rst

+
+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 want to submit your module to the General Community Collection, you can find those guidelines here [FIXME: link].


Is the General Community Collection the same as "Ansible Community Content Collections"? And if so, does that mean pip install ansible will eventually be able to add more content that is not in Ansible 2.9 out of the box?

@geerlingguy updated to say:

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).

How does that sound?

geerlingguy · 2020-02-17T21:17:25Z

README.rst

+
+If you want to submit your module to the General Community Collection, you can find those guidelines here [FIXME: link].
+
+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. 


Note that not all collections will necessarily accept new modules.

I don't think this sentence is necessary; it's not like it's an expectation that anything will be accepted into any open source project anyways (it wasn't that way with ansible/ansible before, either).

I think it's important to point out that not all collections will share the same guidelines.

@geerlingguy I understand that, though if the collection isn't (partly) managed by Ansible then we can't offer even the vague promises of merging code that we did in ansible/ansible.

@gregdek I added

nor follow the guidelines that ansible/ansible previously did.

To hopefully make your point even clearer.

geerlingguy · 2020-02-17T21:18:16Z

README.rst

+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 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.


Is there already a mapping? It could be good to make it polished enough people could reference it on their own—otherwise people are going to be filing tons of issues against ansible/ansible anyways.

botmeta has new field 'migrated_to' which will have collection name from galaxy

Details of BOTMETA & migrated_to: will be added once ansible/ansible#67538 is merged

Link added

gregdek · 2020-02-18T23:41:00Z

I think this is good enough to clean up and push live on Wednesday.

README.rst

jillr · 2020-02-18T23:45:23Z

README.rst

+
+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.
+


I don't see any mention in this doc about Core/Supported Collections. I would expect to see a section here about Ansible Core Content Collections.

@jillr Yup, I've deliberately avoided the product side.

I've added

Although this document focuses on Community (upstream) content, there will be Product (downstream) equivalents of the above. Links to the Product documentation will be added once they are available.

How's that sound?

jillr · 2020-02-18T23:46:59Z

README.rst

+
+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 is this required.
+


I assume the last sentence 'When is this required' is meant to be a placeholder/TODO for writing details of when FQCN is required?

Yup. I think that belongs in https://docs.ansible.com/ansible/devel/user_guide/collections_using.html I'll raise an issue in ansible/ansible for that.

README.rst

gundalow · 2020-02-19T15:04:56Z

Thank you everybody that's reviewed this.
This is in a state where I'm happy with it so I've hit merged.
There are a few unresolved bits of feedback above that I've left comments on when you get time.

I hope that between us all we can keep this document updated.

Collections overview

111d49f

gundalow requested review from felixfontein and thaumos February 17, 2020 20:23

gundalow commented Feb 17, 2020

View reviewed changes

README.rst Outdated Show resolved Hide resolved

gundalow changed the title ~~Collections overview~~ Docs: Collections overview Feb 17, 2020

felixfontein approved these changes Feb 17, 2020

View reviewed changes

geerlingguy reviewed Feb 17, 2020

View reviewed changes

gundalow mentioned this pull request Feb 17, 2020

Add SimpleUpdate command ansible/ansible#65074

Merged

gundalow added the documentation Improvements or additions to documentation label Feb 18, 2020

gundalow added this to In progress in Ansible Community project plan via automation Feb 18, 2020

samccann mentioned this pull request Feb 18, 2020

DaWGs (Documentation Working Group) Meeting Agenda 2020 ansible/community#521

Closed

jillr reviewed Feb 18, 2020

View reviewed changes

Akasurde reviewed Feb 19, 2020

View reviewed changes

README.rst Outdated Show resolved Hide resolved

gundalow added 3 commits February 19, 2020 11:29

Review feedback

2bb12a2

ansible-base, versioning, 2.9 bug fixes

90bceaa

dedicated collection

04df49b

gundalow merged commit 40eeb9d into master Feb 19, 2020

Ansible Community project plan automation moved this from In progress to Done Feb 19, 2020

gundalow deleted the intro-docs branch February 19, 2020 15:03

gundalow mentioned this pull request Feb 19, 2020

Community messaging #12

Closed

11 tasks

gundalow mentioned this pull request Mar 31, 2020

[DOCS] Module Examples vs FQCN #40

Closed

samccann mentioned this pull request Apr 3, 2020

[?w] changelog process for collections #18

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Collections overview #3

Docs: Collections overview #3

gundalow commented Feb 17, 2020 •

edited

geerlingguy Feb 17, 2020

geerlingguy Feb 17, 2020

gundalow Feb 19, 2020

geerlingguy Feb 17, 2020

gundalow Feb 19, 2020

geerlingguy Feb 17, 2020

gundalow Feb 19, 2020

geerlingguy Feb 17, 2020

gregdek Feb 18, 2020

gundalow Feb 19, 2020

geerlingguy Feb 17, 2020

bcoca Feb 17, 2020

gundalow Feb 19, 2020

gregdek commented Feb 18, 2020

jillr Feb 18, 2020

gundalow Feb 19, 2020

jillr Feb 18, 2020

gundalow Feb 19, 2020

gundalow commented Feb 19, 2020


		Warning: Dates subject to change

		* On 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.


		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 want to submit your module to the General Community Collection, you can find those guidelines here [FIXME: link].


		If you want to submit your module to the General Community Collection, you can find those guidelines here [FIXME: link].

		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.


		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.


		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 is this required.

Docs: Collections overview #3

Docs: Collections overview #3

Conversation

gundalow commented Feb 17, 2020 • edited

SUMMARY

ISSUE TYPE

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gregdek commented Feb 18, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gundalow commented Feb 19, 2020

gundalow commented Feb 17, 2020 •

edited