On the philosophy of task naming

Get Help
, ,
1

Sometimes I don’t think to much about it so I end up using different styles of task naming in the same project, for example:

  • Install the package (imperative form)
  • Installation of the package (noun form)
  • Installing the package (progressive form)

One ought to stick to the one form… but which one? ChatGPT is insisting that imperative form i.e “Install the package” is the best one, the recommended one and the most used one. While it makes all the sense if you are reading the code, I don’t see much sense for it when you are reading the Ansible output. Let me explain:

# Install the package               # <- Makes more sense if written in the comment
- name: "Install the package"       # <- Makes less sense because this is what the
  package:                          #    the user sees in Ansible output
  ...

The user is more interested in knowing what Ansible is currently doing and what is the current progress. This is especially true for slow tasks that loop over a number of items. So the following gives the user a nice feedback of a long running task:

- name: "Installing the package..."
  package:
  ...
  loop: "{{ package_list }}"

The noun form i.e. “Installation of the package” is like a neutral, middle ground.

The case for progressive form being the preferred one can be seen in Ansible’s internal tasks like “Gathering facts” or “Validating arguments against arg spec …”.

What are your thoughts?

  • Imperative form → Install the package
  • Noun form → Installation of the package
  • Progressive form → Installing the package
  • Other
0 voters
2

Declarative form: ‘Ensure we have <package>’

2 Likes
3

Should have added it as a fourth option :upside_down_face:. Don’t know if poll will keep the votes if I edit now :worried:

On the other hand, declarative “Ensure” style can also be imperative or progressive:

  1. “Ensure we have a package”
  2. “Ensuring we have a package”
1 Like
4

Since the idea for Ansible to “set a state” (ie, package present/package is absent), I’d go with “Ensure we have ”

1 Like
5

There are only two hard things in Computer Science: Cache invalidation and naming things :rofl:

I’m not sure if there’s an easy answer to you question. If you work alone, use whatever works best for you. If you work together with others, use whatever works best for your team.

Probably not a very helpful answer, but there it is… it depends :person_shrugging:

Personally, I think I would prefer the imperative form (“install” instead of in “installation” or “installing”). I would also prefer “install” over “ensure”, but there’s no accounting for taste.

BTW if you’re installing several packages like Apache, MySQL and PHP in a loop to create a LAMP stack, I think “install (or whatever) packages” isn’t really helpful. In that case, “install web server and dependencies” or “install LAMP stack” might be better. People will see what this task is about then. But as I’ve said: Whatever works best for you / you and your team.

2 Likes
6

to add to the bikeshed, simpler imperative:

We have <package>', but as @mariolenz stated, the best naming convention is the one that makes sense to all those maintaining it.

1 Like
7

You forgot off by one errors

1 Like
8

Big vote for the “Ensure …” option

2 Likes
9

yeah, +1 for “Ensure …”. We’ve also dozens of task names starting like that :smiley:

1 Like
10

I would add to this “Design it so that a person (5/10/100) years from now can easily understand what the task is doing, even if they have zero understanding of Ansible”. This could mean the name has 2 words or 20 LOL

Some examples of task names in various playbooks/roles of mine:
name: Install tomcat {{ tom_ver }} to {{ tom_dir }}
name: Check if HTTPD is installed
name: Security - Firewalld - Permit traffic on port 443/tcp

1 Like
11

I know this doesn’t exactly cover your question, but I think you’re going the wrong direction with your task names altogether. It’s not about the grammar, it’s about the content of the name:. Let me show you.

My advise would be to not use name: Install(ing) package., but rather name: Install prerequisites for SoftwareX. or name: Install build dependencies for ComponentY. or even name: Install prerequisite packages for SoftwareX as required by documentation at https://doc.example.com.

Your goal should be to describe why you run the task and what information others would need to modify the task without breaking anything. Users will figure out that you’re installing a package if the next line says something like ansible.builtin.package. Give additional information and context. This will lead to taskfiles that are machine-readable code and useful human-readable documentation at the same time.

Oh, and to get back OT: I wouldn’t necessarily use the Declarative form that most people here seem to favor. The “Ensure that” part is implied in Ansible’s basic functionality. You wouldn’t write name: Install packageX or do nothing. either; everyone knows that we’re writing idempotent code. Personally, I like the PowerShell way of naming things (like functions in imperative code), which is “Verb-Group”. Ansible does this in a similar way for some of its modules, like get_url. So, imperative would be my vote.

2 Likes
12

Hi @JoergSachse, thanks for the answer. I understand what you are trying to say. Task naming in general should be as descriptive and useful as possible.

What I didn’t anticipate is that people that commented here gave all attention to the act of package installation and how it can be done or described properly. My question was never about package installation per se or descriptiveness of task names. “Install the package” was just some random and deliberately short example showing different forms (imperative, progressive…) of task naming. Maybe I should have picked some more neutral or abstract example instead.

Let me try to describe my concern once again. Given these forms:

  • Imperative form (Do that and that!)
  • Noun form (We are currently in this step)
  • Progressive form (We are currently doing that and that…)
  • Declarative form (Ensure that and that) - although as I pointed out, this can also have imperative and progressive sub form

which form makes more sense to the end user that is looking at the Ansible output?

Ansible playbook is a process that has steps (tasks). Each step takes some time to finish. For me, it makes more sense to use progressive form to inform the user of what is currently going on. Imagine an installation wizard informing the user of what it is doing at that particular moment… yeah I know, I once again chose the act of installation as an example :smile:… bad example.

Imperative form makes sense when you are implementing the playbook because at that point you are effectively ordering Ansible, what to do, task by task. But when you run the playbook and follow the output, it makes less sense to see “Do that and that” in the output. Who is ordering who there?

I hope this alleviates the confusion :sweat_smile:.

13

This is a great question, and you’ve asked it really well. We (my group at work) started using Ansible in March, 2017, and in some form this question goes through my head every time I name a task. Every. Single. Time. Even for one-off, throw away tests, I still feel like whatever name I come up with is somehow wrong.

(@mariolenz already referenced Phil Karlton’s comment about two hard things in computer science, but it never gets old to me.)

So not having what I feel is an adequate answer, I’ll instead relate this counter example. No, literally: it’s a counter. We have this one product that is so ornery to install or upgrade that we’ve divided our install and upgrade playbooks into multiple phases, each phase consisting of tasks that as a group might have a chance of succeeding, or on a bad day constitutes how much work we can practically undo before we try again. (You have to pay big bucks for enterprise software this flaky. If this were opensource it would have been fixed or replaced years ago.)

To the point: every task’s name includes the phase and task number. A block gets its own number and tasks within get a dotted number within. So we have task names like

- name: Upgrade phase3-12/14 - Generate password file on node 1 (head)
- name: Upgrade phase3-13/14 - Wait until all Coordination Service, Administration Agent, Administration Controller, License Manager, and Client File services are running
- name: Upgrade phase3-14.0/14.2 - Block - Upgrade TSM
- name: Upgrade phase3-14.1/14.2 - Upgrade TSM first attempt
- name: Upgrade phase3-14.2/14.2 - Upgrade TSM second attempt, from rescue block

Our upgrade playbook has six phases; our “install” playbook has 20. :exploding_head:

I’m not recommending this generally, although it solves a problem for us, which is that upgrades and installs of this particular product involve so many manual do-overs that it really helps to know where some part of the copious job logs fits into the overall process. Unfortunately, we still spend way too much time pouring over logs.

If you do come to any guiding principles for task naming, whether from this thread of elsewhere, I and I’m sure others would be glad to see them articulated.

1 Like
14

there should be easy way to do this as a callback once you add ‘phase’

1 Like
15

Not to split hairs, but arguably the “Ensure…” form is an imperative form, only more specific.

As a rule of thumb I would avoid the one-size-fits-all approach. The Ensure option is going to be a good fit for many (most?) of the cases, but not all of them. Tasks that have idempotency, for example, are probably better suited with “Install X” or “Create Y” or some other command.

Just my 2p

1 Like