Thank you for considering contributing to Archer.
To install all of the requirements at once:
pacman -S git docker make python-pipenv
The development environment contains a few useful tools. Before testing or working on Archer, the development environment should be activated. This will ensure you have access to the development tools.
$ cd path/to/archer
$ pipenv shell
# Do this on first run, or if Pipfile.lock has changed
$ pipenv sync --dev
Roles in Archer are tested using [molecule][molecule-docs]. To test a role,
navigate to the directory of the role you wish to test...
cd roles/foo
...and run the test(s):
molecule test
A Makefile is included with a target defined to test every role without
having to manually change into each directory. To use this, simply ensure that
you are in the project root, and excecute the following command:
make test
New roles should be generated with molecule, and from a template included in
the roles/templates directory. Because molecule will generate the role in
your current directory, you should make sure you are in the roles directory to
begin with.
Generating a new role from an included template will create the new role
directory, and set up the basic file structure for testing with molecule.
$ pipenv shell
$ cd roles
$ molecule init template --url templates/NAME
Replace NAME with the name of the template you wish to use. Template names
map to the driver molecule will use when creating the virtual environment for
the role's tests. Archer currently supports the following template names:
- docker
You will be prompted for a few values:
| Parameter | Description |
|---|---|
role_name |
The name of the new role |
description |
A description of the role for Ansible Galaxy |
tags |
A space-separated list of tags for Ansible Galaxy |
You now have a new directory in roles/ with boilerplate code for a new task,
including a basic test scenario and a pre-populated metadata file for Ansible
Galaxy.
Tasks should be added to roles/your_role/tasks/main.yml. If you are new to
Ansible, we suggest reading the Getting Started guide to learn
about Ansible.
Because of Archer's design goals, both roles and tasks should be tagged.
Tasks are tagged to ensure consistency throughout various workspaces; for
example, if an individual role is copied out to another workspace. Tags for
tasks in this project exist under the sudoforge.* namespace with a name
related to the role, such as sudoforge.hostname. There are exceptions to this
rule:
| Tag name | Use case |
|---|---|
aur |
The task relates to an AUR package |
notest |
This task should be skipped during tests |
chroot |
This task works in a chroot sandbox |
In a chroot sandbox, such as when you are first installing Arch Linux on a machine, certain tasks will fail, such as those attempting to access files that are outside of the chroot environment.
Every task in Archer should run successfully in a live, working environment. By
providing the chroot tag to tasks, we can enable users to run Archer while in
a chroot jail, thus providing inital machine configuration during installation,
such as creating users, configuring the boot loader, installing a desktop
environment, and more.
See the Change root entry on the Arch Wiki to learn more.
If a task relates to the AUR in any way, such as installing a package from the
AUR, it should be tagged with aur. This is to enable users to easily skip all
AUR packages if they wish to.
Archer's role templates configure the test instance provisioner (Ansible) to
skip tasks that have the notest tag. Ideally, we would not need to use this,
however, there are certain things (like setting the hardware clock) that simply
do not work in virtual environments.