# 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

```yaml
# 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:

```yaml
- 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:

```yaml
- 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'