110 lines
3.8 KiB
Markdown
110 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
# 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:
|
|
|
|
```yaml
|
|
# 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:
|
|
|
|
```yaml
|
|
- 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:`
|
|
|