# \[Vote ended on 2024-01-30\] Ansible collection inclusion requirements: remove absolute ban of \`undocumented-parameter\` ignore.txt entry **URL:** \ **Category:** Project Discussions\ **Tags:** implemented, requirements, collections, community-wg\ **Created:** [December 23, 2023, 12:28pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055 "2023-12-23T12:28:05Z")\ **Posts on this page:** 11\ **Page:** 1
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [December 23, 2023, 12:28pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/1 "2023-12-23T12:28:05Z")
Right now the [Ansible collection inclusion requirements on CI testing](https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_requirements.html#ci-testing) explicitly state that `undocumented-parameter` is one of the errors you MUST NOT ignore in `tests/sanity/ignore-*.txt`. Some collections in Ansible violate this rule, but (at least the cases I know of) for good reasons. Proposal: update the collection requirements so that `undocumented-parameter` in tests/sanity/ignore-\*.txt is allowed in specific circumstances: 1. deprecated parameters; 2. internal parameters used to transport data from an action plugin to a module. More precisely, see my PR [Collection requirements: undocumented-parameter must only be used for deprecated parameters or internal parameters by felixfontein · Pull Request #989 · ansible/ansible-documentation · GitHub](https://github.com/ansible/ansible-documentation/pull/989) which changes the wording. Rationale for exception 1: This has been used in the past when removing dangerous parameters to make sure that users get a useful error message. One such case was [Remove the params module option from ldap\_attr and ldap\_entry (#113) · ansible-collections/community.general@11ef03e · GitHub](https://github.com/ansible-collections/community.general/commit/11ef03e9dd1dc05fd80bbe74eafd89b3645965cf). Rationale for exception 2: If code has to be spread over both an action plugin and a module, some data often needs to be passed from the action plugin to the module. The only way to do this is to add a module parameter. The validate-modules sanity tests requires this parameter to be documented, which is wrong since the user cannot use that parameter - it is provided directly by the action plugin. Since there is no mechanism to disable the error for a specific module parameter, it needs to be disabled completely. Example: [community.docker/plugins/action/docker\_container\_copy\_into.py at main · ansible-collections/community.docker · GitHub](https://github.com/ansible-collections/community.docker/blob/main/plugins/action/docker_container_copy_into.py#L28) → [community.docker/plugins/modules/docker\_container\_copy\_into.py at main · ansible-collections/community.docker · GitHub](https://github.com/ansible-collections/community.docker/blob/main/plugins/modules/docker_container_copy_into.py#L776). What do you think? ---
**Author:** ![mariolenz](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/mariolenz/32/108_2.png) [@mariolenz](https://forum.ansible.com/u/mariolenz)\ **Post date:** [December 25, 2023, 3:03pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/2 "2023-12-25T15:03:15Z")
Exception 1 makes sense to me. Actually, I think it might be worth to reconsider the absolute ban of _all_ ignores for deprecated parameters. I’m not 100% sure about exception 2. Is it possible to mark a parameter as (collection) internal? Your proposal makes sense, but this would make it easier IMHO: I think it would be easier to (automatically) allow more ignores if parameters are marked as internal only. If it isn’t possible to have collection internal paramaters for modules we might have to talk to the core team to make it possible. ---
**Author:** ![jborean](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/jborean/32/1525_2.png) [@jborean](https://forum.ansible.com/u/jborean)\ **Post date:** [January 3, 2024, 7:28pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/3 "2024-01-03T19:28:48Z")
Why not just document it and say it’s for internal use only. While I would love for a way to explicitly mark something as internal only so you don’t have to document it at all, I find that using the ignore files is the wrong thing for something like this. ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [January 3, 2024, 8:20pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/4 "2024-01-03T20:20:37Z")
I find it very strange to document options that cannot (and must not) be used. (Same as for modules/plugins/roles for internal use of a collection.) If the users provide values for these options, in the best case they receive an error message, and in the worst case the value is simply ignored. So why should they be listed in the documentation at all? We don’t document other random names that cannot be used as options for a module/plugin/role either. > [@jborean](#): > > While I would love for a way to explicitly mark something as internal only so you don’t have to document it at all, I find that using the ignore files is the wrong thing for something like this. I fully agree with that. In fact I suggested something for that roughly a year ago: [Allow to mark module parameters as undocumented / private · Issue #79695 · ansible/ansible · GitHub](https://github.com/ansible/ansible/issues/79695) This was discussed at a core meeting: [Meetbot Logs](https://meetbot.fedoraproject.org/ansible-meeting/2023-01-12/ansible_core_public_irc_meeting.2023-01-12-16.00.log.html) I don’t remember the details, but the result was that nothing happened, and we still have to add ignore.txt entries that globally disable some error classes for a module/plugin… ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [January 3, 2024, 8:59pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/5 "2024-01-03T20:59:41Z")
> [@mariolenz](#): > > I’m not 100% sure about exception 2. Is it possible to mark a parameter as (collection) internal? Your proposal makes sense, but this would make it easier IMHO: I think it would be easier to (automatically) allow more ignores if parameters are marked as internal only. If it isn’t possible to have collection internal paramaters for modules we might have to talk to the core team to make it possible. That’s why I opened [Ansible collection inclusion requirements: remove absolute ban of `undocumented-parameter` ignore.txt entry - #3 by jborean](http://forum.ansible.com/t/ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/3) a year ago 🙂 I would prefer something like that, but right now it’s not possible, and it doesn’t look like it will change anytime soon. ---
**Author:** ![jborean](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/jborean/32/1525_2.png) [@jborean](https://forum.ansible.com/u/jborean)\ **Post date:** [January 3, 2024, 9:08pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/6 "2024-01-03T21:08:08Z")
> I find it very strange to document options that cannot (and must not) be used. (Same as for modules/plugins/roles for internal use of a collection.) Sure but I find it stranger to ignore an explicit check rather than just 2-3 lines saying this is internal and not to use. My preference would be to have a common mechanism to mark options as internal/do not use so they don’t have to be documented but turning off the check for the whole documentation might lead to other errors falling through. In the current landscape documenting them as internal to me is the lesser of two evils here. ---
**Author:** ![briantist](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/briantist/32/130_2.png) [@briantist](https://forum.ansible.com/u/briantist)\ **Post date:** [January 3, 2024, 9:08pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/7 "2024-01-03T21:08:42Z")
This probably doesn’t apply too much to this thread but ICYMI, there’s been a change in `devel` that affects plugin options using config manager: - [Fix plugin set option by bcoca · Pull Request #82300 · ansible/ansible · GitHub](https://github.com/ansible/ansible/pull/82300) With that change, attempting to set an option with `set_option` or `set_options` that isn’t documented, or is documented with a wrong/incompatible type to its value, will raise an exception. I wonder if in some cases, that might end up requiring documentation of internal options used in action plugins (though I guess they just would not use config manager). ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [January 10, 2024, 7:33pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/8 "2024-01-10T19:33:36Z")
If there are no new arguments, or objections, I’ll start a vote on this in a few days. ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [January 16, 2024, 8:41pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/9 "2024-01-16T20:41:55Z")
Please vote until **2024-01-30** in the following SC/community vote on whether [[WIP] Collection requirements: undocumented-parameter must only be used for deprecated parameters or internal parameters by felixfontein · Pull Request #989 · ansible/ansible-documentation · GitHub](https://github.com/ansible/ansible-documentation/pull/989) should be merged, and with it the absolute ban of `undocumented-parameter` in `tests/sanity/ignore-*.txt` removed: _Poll ([view on site](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/9))_ _Poll ([view on site](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/9))_ ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [January 31, 2024, 5:36pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/10 "2024-01-31T17:36:23Z")
Counting votes: - SC: 7 x +1 (felixfontein, gotmax23, briantist, Andersson007, mariolenz, markuman, gundalow), 1 x -1 (acozine) - Community: 2 x +1 (cybette, Leo), 0 x -1 ---
**Author:** ![gotmax23](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/gotmax23/32/106_2.png) [@gotmax23](https://forum.ansible.com/u/gotmax23)\ **Post date:** [January 31, 2024, 5:37pm UTC](https://forum.ansible.com/t/vote-ended-on-2024-01-30-ansible-collection-inclusion-requirements-remove-absolute-ban-of-undocumented-parameter-ignore-txt-entry/3055/11 "2024-01-31T17:37:46Z")
I can confirm your count!