NETWAYS / NETWAYS/ansible-collection-elasticstack

Define the collection-wide variable naming schema

Open
#542 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

component:all documentation quality
Dominant language
Jinja
Stars
14
Forks
11
Avg merge
1d 47m
Merged PRs (30d)
6

Description

Problem

Variable names in the collection follow no single documented schema. Same concept, different
words (_pass / _pw / _password / _passphrase), mixed boolean forms (_enable 6x vs
_enabled 2x), negative booleans (no_*, disable_*), a typo (indicies), and names that do
not say what the value is (elasticstack_password is the elastic user's password,
elasticstack_initial_passwords is a file path). Without a written schema, every issue that
renames a variable has to re-decide the rules.

Want

Agree on one naming schema and document it in CONTRIBUTING. This issue only defines and
documents
the rules; applying them is a separate issue.

Schema (proposed)

  1. Prefix - <role>_ for role-owned variables, elasticstack_ for stack-wide ones (read by

    = 2 roles). Which variable belongs where is decided in #485 / #495, not here.

  2. Internals - __<role>_<name> for register / set_fact, _<role>_<name> for vars/
    (see #495).
  3. Credentials - _password for an account credential, _passphrase for something that
    protects a key or keystore. Never _pw, never _pass.
  4. Booleans - positive polarity only, no no_* / disable_*.
  5. Boolean suffix - _enable everywhere. It is an instruction to the role, consistent with
    the existing manage_* family.
  6. Word order - <prefix>_<subject>_<attribute>, e.g. ..._repos_enable, not
    ..._enable_repos.
  7. Paths - the name carries _file / _dir / _path.
  8. Spelling - correct English (indices, not indicies).
  9. Units - put a unit in the name only when type: and the description in
    argument_specs.yml do not already carry it. Example: *_cert_expiration_buffer needs no
    _days suffix because the spec declares type: int and the description says "in days".

Scope

  • Agree on the rules above
  • Document them in CONTRIBUTING

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the proposed naming rules in this issue, then read CONTRIBUTING and the referenced issues #485 and #495 for role ownership and internal variable conventions. Document the agreed schema in CONTRIBUTING; done means the rules are agreed and the checklist item is complete, without applying renames.

Written by the indexing model from the issue text.

Assessment

Tech stack
ansible
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.