'"include" is deprecated, use include_tasks/import_tasks instead.' deprecation warning is without link to place explaining how to deal with it

[matkoniecz]

Summary

I noticed

[DEPRECATION WARNING]: "include" is deprecated, use include_tasks/import_tasks instead. This feature will be removed in version 2.16.

Sadly, this deprecation warning is without link to documentation explaining how it should be fixed

I went to changelog: but https://github.com/ansible/ansible/blob/devel/changelogs/CHANGELOG.rst is not really helping with finding documentation

searching import_tasks include_tasks difference ansible on internet found finally https://serverfault.com/questions/875247/whats-the-difference-between-include-tasks-and-import-tasks

Every single person using Ansible will need to search for about 2 to 10 minutes - multiply it by number of Ansible users and there is quite big waste of time.

If there is a good reason to deprecate something - please link to documentation explaining how to fix code that worked fine so far.

Or maybe at least mention which version is equivalent to the current behaviour.

(ideally there would be ansible undeprecate_include which would edit all instances of include to whichever version is matching current one and ansible undeprecate_include include_tasks which would use include_tasks and ansible undeprecate_include import_tasks)

Issue Type

Documentation Report

Component Name

ansible (sorry)

Ansible Version

$ ansible --version

ansible [core 2.12.1]
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/mateusz/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3/dist-packages/ansible
  ansible collection location = /home/mateusz/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/bin/ansible
  python version = 3.8.10 (default, Nov 26 2021, 20:14:08) [GCC 9.3.0]
  jinja version = 2.10.1
  libyaml = True

Configuration

$ ansible-config dump --only-changed

(no visible output)

OS / Environment

Lubuntu 20.04

Additional Information

No googling needed to find docs, lower risk of finding misleading docs

Code of Conduct

• I agree to follow the Ansible Code of Conduct

[matkoniecz]

My reading is that replacing all by import_tasks is safe if I am not doing anything weird like dynamically generating/editing task files or conditionals ( https://docs.ansible.com/ansible/latest/user_guide/playbooks_conditionals.html#applying-when-to-roles-imports-and-includes ).

[bcoca]

link https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_includes.html

[sivel]

This link is more specific I think:

https://docs.ansible.com/ansible-core/2.12/user_guide/playbooks_reuse.html#re-using-files-and-roles

[philipfreude]

It would also be useful to be able to see the files and line numbers where a deprecated "include" is still used.

[sivel]

grep -HRn ' include:' *

[bcoca]

we try to keep the warnings generic so we can dedupe, otherwise the user would be flooded with warning messages if they have multiple includes in the play. Also easy to find them as @sivel has already pointed out (git grep also works!)

[samccann]

Notes on how to include a link in an error message like this:

Here's an example: https://github.com/ansible/ansible/blob/devel/lib/ansible/executor/interpreter_discovery.py#L130 - I n place of including a static URL when an error message is being built, use get_versioned_doclink (from ansible.utils.plugin_docs) with a relative link to the as-rendered filename from the versioned root of the docsite. eg: get_versioned_doclink('reference_appendices/interpreter_discovery.html') in 2.12 comes out in the error message as https://docs.ansible.com/ansible-core/2.12/reference_appendices/interpreter_discovery.html

[samccann]

Actual file where this error message exists is - https://github.com/ansible/ansible/blob/devel/lib/ansible/playbook/helpers.py#L158

and the relative doclink is user_guide/playbooks_reuse_includes.html

will need to add from ansible.utils.plugin_docs import get_versioned_doclink to top of file as well.