module metadata

[bcoca]

Proposal: module metadata (REVISED)

Author: Brian Coca @bcoca

Date: 2016/08/32

• Status: New
• Proposal type: module management
• Targeted Release: 2.3
• Estimated time to implement: weeks

  Motivation

Managing modules and identifying their applicability is a problem, this proposal aims to add metadata entry to modules to give more information to those managing and classifying them, not needed at run-time but for decisions made prior about viability and availability.

Problems

• core/extras divide: this allows us to have all in single repo and then use the metadata to classify the modules.
• support: currently this is unclear to users.
• state: hopefully we can give users indications on how stable a module's interface is.

  Solution proposal

Add a METADATA variable to the modules (like current DOCUMENTATION, EXAMPLES, etc)

METADATA = """
    support: community|contrib|core
    status: preview|stable|deprecated|removed 
    version: 1 # version of metadata format
    language: 
      name: python  # this is default
      versions: [2.4,2.6,2.7,3.5]  # default is [2.4-2.7, 3.5]
      OS: 
        - POSIX # this is the default

• support:
  • community: not supported nor revised by Ansible, purely community supported
  • contrib: supported mostly by community and curated by Ansible.
  • core: supported by Ansible
• status: # does not indicate code quality but likelyhood of breaking existing plays, data on deprecation and removal dates should appear in module docs, as well as alternate plugins
  • preview: interface (options) might change in backward incompatible ways
  • stable: interface will not change in backward incompatible ways
  • deprecated: will be removed, only critical bugfixes will be applied
  • removed: has been removed, only documentation exists for historical purposes
• language: versions could allow for range expressions i.e 3.5+ or >=3.5 and 2.4-2.7, not sure if we need name=python as I don't see this applying to modules in other languages. never mind .. powershell.
• OS: a list of what a module supports, for example systemd is Linux specific. But we can have more, just need to standardize on naming, versions and groupings:

      - Windows # i.e win_user
      - BSD  # subset of POSIX and superset of other BSDs rc_service module
      - FreeBSD-10 # this module only works for FreeBSD-10, i.e rc_ctl  service module

Newly contributed plugins would default to support: community and status: preview.

Documentation

Pertinent metadata should be reflected in the documentation website and also in ansible-doc output.

Additional

Aside from status and support all of the above are optional, can be added later on. Also this can also be easily expanded, for example, if we partner with some other entity to let them support specific modules we can add:

    support: community|contrib|core|team
    team: # (only if support=team)
      name: team_name
      url: http://www.example.com/support

We've also been looking at testing info:

tests: yes

or

coverage:
  unit: yes
  integration: yes

[gundalow]

1) Do we need to detail at what version we added the deprecation notice(status=deprecated)?

2) Do we need to detail which version removed this module (status=removed)?

3) We will need to review and remove the existing from modules:

requirements:
  - python >= 2.6

4) If we are going to be making changes to how documentation is produces is now the time to have versioned documentation online

docs.ansible.com/v2.2/lineinfile_module.html
docs.ansible.com/devel/lineinfile_module.html

[bcoca]

1 & 2) we already do this in module docs, that metadata was only reflecting 'current state', but no reason we cannot expand:

deprecated: "2.2"
removed: "2.4"

3) I'm not sure if this will work as a substitute, it might make sense to keep it in requirements, either way works for me.

4) For the docs, we've been planning for a long time /devel and /stable, keeping per version just creates too big a maintenance burden.

[gundalow]

I'm happy with that as long as we don't duplicate data.

[gregdek]

So given this, I assume that new modules, once they pass the automated tests and very basic review, would come in as "community" and "preview", right? I presume:

• Promotion from "community" to "contrib" happens when core team decides they need to have more oversight because a module is becoming more central;
• Promotion from "preview" to "stable" happens when a package has been well-maintained-ish for a while?

I might recommend replacing "preview" with "unstable" so that it can be a bidirectional state; i.e. we can demote modules from "stable" to "unstable" if the reviewer disappears. But other than that, I think this model looks pretty good.

[bcoca]

preview/stable will probably require 'age' or core curation/support, it is a commitment that the interface won't change.

As such i can see promoting but there should be no demoting, this is more of a policy issue than a support one. That is why I avoided 'unstable' as it looked more like code quality/support than anything else, but I'm fine to change the names to whatever people think is more appropriate.

[abadger]

We discussed and combined this with https://github.com/ansible/proposals/issues/30 Closing this so there's only one ticket to track.