ansible_role_package/CONTRIBUTING.md

Contributing

Package definition

A "package" is just a yaml task list that defines how to install a piece of software. It does this through the use of helpers that manage;

• dependency installations
• building from source
• linking binaries to a usable PATH
• calling external tools when required
• installation via package managers on the system

Anatomy of a Package Definition

It starts with package metadata, as a comment block above the installation steps. This should come after the line # vim: set filetype=yaml.ansible :, which sets up the correct linter and language server when using neovim/vim.

Metadata

The metadata consists of at minimum 6 key: value pairs

# Package: <package name>
# Description: <package description>
# Version: <latest supported version of package. 'latest' is fine>
# Methods: <list of available methods for installation>
# Helpers: <list of helpers used by the package directly>
# Maintainers: <list of maintainers for this package>

This list should match package defaults where it makes sense, for example, the Version: should match the default installed version of the package.

Configuration acknowledgement

The "Configuration acknowledgement" MUST be at the start of the yaml file, and cover everything this package does. This is important for gating when a package should be configured or not.

It looks like this, using the air package:

- name: Start air configuration
  when:
    - "'air' is not in __configured"
  block:
    - name: Configure air installation method
    ...

    - name: Finalize air configuration
      ansible.builtin.set_fact:
        __air_configured: true

or alternatively:

- name: Start air configuration
  when:
    - __configured['air'] is undefined

This way, if a package is included as part of another packages build, it only happens once.

Setting and adding package configuration to list

Adding the configuration for a package is done by appending the configuration to the appropriate list. Each helper has it's own installation block in tasks/main.yml.

Depending on the package installation method, the package must be added to the appropriate list.

Different lists, and when to use them

The following is a list of the different lists that are used, and the order they are run.

• system: pkg_sys
  • Only for packages installed from the system package manager
  • If a package adds a repository to handle the system installation, it should be done in the package configuration itself. For example, installing ghostty via the system package manager requires adding a copr repo on fedora. This should be done in a section named 'Adding copr repository scottames/ghostty'