Contributions to Armory are welcomed and highly encouraged! Armory contains a complex suite of tools that both configure the execution
environment and compose a set of objects (from an experiment file) to be executed in said environment.
Primarily, Armory has two main modes of operation:
- Native (also known as
--no-docker) mode - This uses a pre-set python environment to execute the configuration file. - Docker - This uses docker to compose and launch docker images, and executes the armory experiments within the container.
For more details, including how to set up your development environment for either mode of operation see: Setting up Development Environment
Armory Development follows the GitHub Standard Fork & Pull Request Workflow.
Armory uses GitHub Actions to test contributions, for more details see Armory CI. Generally it will be most useful to set up the Armory pre-commit hooks. For more information see the Armory Style Guide.
Armory follows the GitHub Standard Fork & Pull Request Workflow and therefore, to
get started with contributing to armory, you will first need to head over to https://github.com/twosixlabs/armory
and fork the repo. Once forked, clone that fork to your computer and cd into the forked repo location (herein refered to as [armory-fork-repo]).
From here, you will need to setup your python virtual environment and, depending on your use case, other applications such as Docker. The following section will describe the details here in a bit more detail.
Armory can run natively within a python virtual environment on a host machine. To get setup you will need to
create a virtual environment. Once created and activated, you will need
to install some additional requirements. Typically, it is useful to use the -e flag with the armory pip so that it
will point to your local directory, therefore utilizing code edits without requiring follow-on installs. To accomplish
this run:
cd [armory-fork-repo]
pip install -e .[tests]
pip install -r host-requirements.txtNow that you have the environment setup, kickoff the baseline tests to make sure its all good:
pytest -s tests/test_hostdepending on you $PATH, pytest might refer to a pytest outside your virtualenv, which can cause issues. As
an alternative you can use (make sure your virtualenv is active):
python -m pytest -s tests/test_hostIf this is successful you are off to the races! If you would like to run armory in --no-docker mode, see:
Armory No Docker Setup.
Armory can utilize docker to launch containers for execution of armory experiments. For information on how to install docker on your machine see: Docker Installation.
Once docker is installed, armory downloads and launches containers based on the __version__ string found in armory.__init__.
Note: only release versions of armory will be published to Dockerhub, therefore, development branch images much be built locally using:
cd [armory-fork-repo]
bash docker/build.sh <tf2|pytorch|pytorch-deepspeech|all> devArmory enforces code / file styling using Flake8, black, yamllint, etc. For more information about how we configure these tools, see Armory Style Guide.
We gladly welcome pull requests.
If you've never done a pull request before we recommend you read this guide to get you started.
Before making any changes, we recommend opening an issue (if it doesn't already exist) and discussing your proposed changes. This will let us give you advice on the proposed changes. If the changes are minor, then feel free to make them without discussion.
When adding new features please add test cases to ensure their correctness. We use pytest as our test runner.
For running pytest, users should follow .github/workflows/ci_test.yml.
This has tests for docker and native modes as well as formatting.