[Vote ended on 2023-03-09] How should private modules/plugins be marked?

[felixfontein]

Discussion: #154, in particular #154 (comment)

This vote is not about whether it should be possible to mark modules/plugins as private, but about how to do this. The idea is to create a concrete proposal that can be further discussed / voted on.

There are three proposals. Please vote a), b), c), or other (and state what you would prefer).

a) Use a leading _ prefix in the plugin/module name to indicate that the plugin is private (Python convention);
b) Use a private: true entry in meta/runtime.yml's plugin_routing (next to deprecate, tombstone, redirect);
c) Use something in the plugin/module's DOCUMENTATION (similar to version_added, description, etc.)
d) Something else.

Please note that c) is problematic since it makes listing all plugins/modules less efficient, since it would have to read every module/plugin file to check whether the metadata is present. Right now for listing, ansible-doc only needs to scan the file until short_description appears (and will stop reading it at that point) - a new metadata field might or might not be present, so the scanning code will become more complicated and definitely slower since it has to read until the end of DOCUMENTATION and do more processing. (This is listed here for completeness, since several folks asked about it.)

Linked downstream ticket https://issues.redhat.com/browse/AAP-9875 raised by @ssbarnea

[felixfontein]

b) (and alternatively a), and definitely not c))

[gotmax23]

+1 to a

[briantist]

b)

[maxamillion]

b)

[mariolenz]

I would prefer something in the way of c, but due to the problems mentioned an in view that using an underscore _ is very Python (while modules can be written in a lot of programming languages) I say:

+1 for b

[tremble]

+1 for b (for what little my votes worth). It would however be good if docs still got generated as "orphans" with a nice warning at the top.

_ has historical meaning in the context of Ansible that I'd be weary of re-using.

tweaking the docs feels like a hack.

[acozine]

+1 for b.
+/-0 for c.
-1 for a.

[markuman]

b)

[Andersson007]

+1 b

[kristianheljas]

b)

[leogallego]

+1 for b

[bcoca]

-1 to having hidden plugins. This goes against the principle of auditability as it obscures the actions taken in the playbook from the reader.

I'm fine if you label the plugins 'for internal use only' in the documentation, but I don't think this should affect the runtime code in any way, neither hiding them from listing nor disallowing the use outside of the original package.

I understand the desire of some developers to ship things that are 'good enough' for their uses but not for public consumption, but in the interest of auditability and simplicity I strongly oppose such a feature.

[ssbarnea]

From the devtools point of view, we a text/description based approach for declaring what is private wound not. That is because it makes impossible to implement programmatic behavior in tools like ansible-language-server and ansible-lint.

We need a clear way to distinguish between what is expected to be public or not, still both extra property and _ prefix are ok, so a) and b) are ok for us.

Also, I think that nobody asked about enforcing the "private" part from ansible point of view. Like with python, we only want to be able to declare stuff as private, not to prevent people from calling private bits, which they might have to in some corner cases.

[cidrblock]

+1 b, self documenting and does not require a decoder ring

[bcoca]

FYI, meta/runtime.yml is not a documentation file nor is it normally reflected in documentation (indirectly via resolution of deprecated/removed content), it is a file for the internal plugin loader

[s-hertel]

-1 for b. This file is ansible-core runtime metadata, so unless ansible-core is doing something with this data, I am in favor of any of the other options by comparison. It could also be an issue for core/the collection if collections are using this as a place to hang unrelated stuff.

d: adopt a convention like 'INTERNAL' as the first line of the plugin description. This would make it easy to filter plugins but not actually obscure them from someone who needs it.

[gotmax23]

Folks, please keep other discussion in the issue and not in the voting thread. Leave a +/-1 here and expand elsewhere.

[felixfontein]

Also please don't write +1/-1 without specifying to which of the choices (a, b, c, d) it applies.