ansible_role_package/CONTRIBUTING.md

Contributing

Package definition

Package defintions are just yaml tasks in the directory tasks/pkgs, which handle how a package is installed.

Most can be installed using the syspkgs list, and are simply appending the package name to said list based on the system.

If a package can be installed via an entry to syspkgs for some, but not all platforms, handling is done to either inform the user that the package is not available, or to append the package name to another installation method such as:

• appimages to install the appimage of a package
• cargopkgs to install via the rust cargo package manager
• cargoversioned to install version lockec cargo packages
• caskpkgs to install a homebrew cask
• flatpkgs to install flatpaks
• gopkgs to install using the go install command
• npmpkgs to install packages from npm
• pipxpkgs to install packages from Python pip
• srcpkgs to build packages from source
• tappkgs to install packages from home brew taps

Alternative sources of packages can be defined with entries to:

• fpremotes to add a flatpak remote
• brewtaps to add a homebrew tap

Adding system level repositories

Many packages exist in their own external repository for the given system, such as /etc/yum.repos.d for RedHat based linux distros, /etc/apt/sources.list.d for Debian based distros and others. Since you an add the package to syspkgs by enabling a repo, the coresponding task in tasks/pkgs should take the steps needed to enable the repository.

Packages with multiple instllation methods

Many packages can be installed in different ways, like the bitwarden package. bitwarden can be installed as a syspkg on some machines, a caskpkg on macOS, an appimage, a flatpak or even a snap.

For such packages, a default is chosen to install, in the following order of precedence: syspkgs, flatpkgs, snappkgs, appimages.

In that order, syspkgs and caskpkgs have equal weight, as it applies to macOS.

Formatting rules

• Use indentation explicitness. Lists should be indented:

# Good
my_good_list:
 - my_list_item

# Bad
my_bad_list:
- my_list_item

• Variables should be in snake case, separating words
• Short names are fine if they are explicit. ie vers can be used instead of version
• If more then one variable starts with the same words, put it into a dict if it makes sense:

# variables that should be a dict
cargo_locked: true
cargo_pkg: alacritty

# better to just be
cargo:
  locked: true
  pkg: alacritty

• Tasks MUST follow the convention in this example:

- name: Capitalize first letter of name
  when:
    - each condition has it's own line
    - (brackets around conditions with) or
      (to show they are separate)
  become: "{{ not use_local }}" # must be able to be used with use_local
  become_user: # this should not be needed, but always follows become if it is
  loop: "{{ my_loopable_list }}"
  loop_control: # **MUST** always use at least loop_var for any loop
    loop_var: my_item
  ansible.builtin.set_fact: # always use the full module name
  ...

• name: Every task needs a name, and the first letter must be capitalized
• when: If a when clause exists, it follows the name
  • Each clause must have it's own line, including and or clause, as seen above
• become: must follow the when clause if it exists, name otherwise
  • Any other become_ settings follow become in alphabetical order
• loop: must be defined just before the module invocation
  • Every loop needs to rename the loop_var to something that makes sense
  • until is consider the same as loop for the purposes of placement
• The last item must be the module invocation, using the fully qualified name
  • For example, don't use set_fact:, use ansible.builtin.set_fact: