Collection requirements: undocumented-parameter must only be used for deprecated parameters or internal parameters #989
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
… internal parameters.
felixfontein
temporarily deployed
to
github-bot
GitHub Actions
Inactive
ansible-documentation-bot
bot
added
the
sc_approval
gotmax23
reviewed
Dec 23, 2023
Comment on lines
409
to
412
| * The following validations MUST not be ignored except in specific circumstances: | ||
| * ``validate-modules:undocumented-parameter``: this MUST only be ignored in one of these two cases: | ||
| 1. A dangerous module parameter has been deprecated or removed, and code is present to inform the user that they should not use this specific parameter anymore or that it stopped working intentionally. | ||
| 2. Module parameters are only used to pass in data from an accompanying action plugin. |
There was a problem hiding this comment.
It doesn't seem the nested ordered list is formatted correctly:
felixfontein
commented
Dec 24, 2023
docs/docsite/rst/community/collection_contributors/collection_requirements.rst
Show resolved
Hide resolved
felixfontein
temporarily deployed
to
github-bot
GitHub Actions
Inactive
felixfontein
changed the title
gundalow
approved these changes
Jan 29, 2024
felixfontein
changed the title
mariolenz
approved these changes
Jan 31, 2024
felixfontein
added
the
backport-2.16
Backport to stable-2.16: 💚 backport PR created✅ Backport PR branch: Backported as #1100 🤖 @patchback |
oraNod
pushed a commit
to BhattacharjeeSutapa/ansible-documentation
that referenced
this pull request
Feb 12, 2024
… deprecated parameters or internal parameters (ansible#989) * undocumented-parameter must only be used for deprecated parameters or internal parameters. * Add newline.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Proposal: update the collection requirements so that
undocumented-parameterin tests/sanity/ignore-*.txt is allowed in specific circumstances:Right now
undocumented-parameteris listed as explicitly forbidden. Some collections in Ansible violate this rule, especially for 2 above. But let me give some more details: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 ansible-collections/community.general@11ef03e.
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: https://github.com/ansible-collections/community.docker/blob/main/plugins/action/docker_container_copy_into.py#L28 → https://github.com/ansible-collections/community.docker/blob/main/plugins/modules/docker_container_copy_into.py#L776.
I'll create a discussion in the forum where we can also vote on this.