From 2fe34b6444502079dc0b84365ce82dbc92de308e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 13 Apr 2024 14:06:49 +0200 Subject: Adding upstream version 6.17.2. Signed-off-by: Daniel Baumann --- docs/philosophy.md | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 docs/philosophy.md (limited to 'docs/philosophy.md') diff --git a/docs/philosophy.md b/docs/philosophy.md new file mode 100644 index 0000000..2ef698d --- /dev/null +++ b/docs/philosophy.md @@ -0,0 +1,109 @@ +# Philosophy of ansible-lint + +Ansible **playbooks, roles, and collections** should read like documentation, be +production ready, unambiguous, and provide consistent results. + +`Ansible-lint` should be considered a trusted advisor, helping ansible content +creators write and package high-quality Ansible content. While not all rules may +be applicable in all situations, they should be followed whenever possible. + +The goal of `ansible-lint` is to ensure that content created by different people +has a similar look and feel. This makes the adoption and use of Ansible content +easier in the community and enterprise. By keeping the number of configurable +features at a minimum, consistent outcomes between authors can be achieved. + +## History and the future + +`ansible-lint` is almost a decade old, and its current list of rules is the +result of a collaboration between many people. The tool originated as a +community project and is currently part of the Ansible Galaxy submission and +validation process. + +In the future, it will be an official component of the Red Hat Ansible +Automation Platform, used during the collections certification process and the +recommended Ansible content linter for Red Hat customers. + +Starting in 2022, additional rules will be added that help content creators +ready their content for production use. It will be through the use of +ansible-lint and these rules, developers can have confidence their playbooks, +roles, and task files are easy to understand and produce consistent results when +run against anything, from servers in a home lab to mission-critical systems in +the cloud. + +## Style and formatting + +The focus of Ansible content creators should be on automation, outcomes and +readability, rather than style or formatting. This is why we follow the same +concepts as other code formatting tools like +[black](https://github.com/psf/black) and [prettier](https://prettier.io/). + +Adoption of `ansible-lint` will save time by keeping reviews focused on the +quality of the content and less so on the nuances of formatting and style. + +As code formatting is not an art, we can save your project time and effort by +applying a standardized code style and formatting. + +## Q&A + +### Why does ansible-lint not accept all valid ansible syntax? + +`ansible-core` continues to mature while maintaining backward compatibility with +early versions. `ansible-lint` has never intended to support the whole +historical Ansible language syntax variations, but instead only the best of it. + +It supports a broad vocabulary of keywords and styles. Over time, changes in the +language have led to an improved experience for authors and consumers of Ansible +content. The rules in `ansible-lint` suggest the use of these patterns. + +It is these usage patterns that are written as rules in `ansible-lint`, leading +to improved readability of **playbooks, roles**, and **collections**. The linter +will always be more restrictive and opinionated regarding what it accepts. It is +part of its design. We are not forced to keep the same backward compatibility +level as Ansible, so we can tell people to avoid specific syntax for various +reasons, such as being deprecated, unsafe, or hard to maintain. + +Based on the extensive history of `ansible-lint` and user feedback, it notifies +you about discouraged practices, sometimes before `ansible-core` starts doing +so. + +### What if I do not agree with a specific rule? + +We recognize that some projects will find at least one rule that might not suit +their needs. Use the `skip_list` feature to temporarily bypass that rule until +you have time to update your Ansible content. + +### Who decides which best practices get adopted in ansible-lint? + +The main source of new ideas was and remains our community. Before proposing a +change, check with a few other Ansible users that work on different projects and +see if they find it useful or not. + +It is better to get enough relevant feedback on our discussion forum before +starting to implement new rules. If the proposed rule appears popular and does +not conflict with existing rules, a core (maintainer) will tell you that the +proposed rule can be added to ansible-lint, so you can start working on it +without fear of rejection. + +The core team will decide on how a new rule will be added. Usually, they are +added as experimental (warnings only) or even as opt-ins, being made implicit +only when a major version is released. + +### Do I need to pass all rules to get my collection certified? + +Not really. The certification process is likely to use only a subset of rules. +At this time, we are working on building that list. + +### Why lots of official Ansible docs examples are not passing linting? + +Most of the official examples are written to exemplify specific features, and +some might conflict with our rules. Still, we plan to include linting of +official examples in the future and add specific exclusions where needed, making +it more likely that a copy/paste from the docs will not raise a bunch of linter +violations. + +### Why does ansible-lint require an Ansible version newer than what I use in production? + +Use `ansible-lint` as a **static analysis** tool for your content. You can run +it with a version of ansible that is different than what you use in production. +This helps you prepare your content for the future, so don't be afraid of using +it in such a way. -- cgit v1.2.3