Contributing

Right now, submission of issues and pull requests through GitHub is the best way to suggest changes, and those will have to be applied and merged on the internal MITRE GitLab and mirrored to GitHub. This process may change in the future.

Contributing Guidelines:

Nobody can commit directly to main.
You must create a merge request in order to publish changes to main.
Before merging, all stages of the GitLab CI pipeline must pass. This includes linting with flake8, code-formatting with black, passing the Python unit tests, and creating the documentation.
Once all pipeline stages have passed, then the branch can be merged into main.
These pipeline stages can be tested locally to ensure that they are passed on the remote side (explained in Using Pre-commit)

Docstrings

Do your best to make sure that all docstrings adhere to the following Google format found in xrl_dataset.py here. The reasoning can be found here. We’re using double quotes for docstrings and strings per the formatting requirements of black.

If you are editing a file and see that a docstring doesn’t adhere to the Python3 Google Style Guide exemplified in xrl_dataset.py here, please be a good steward and fix it so that it does.

Issue & Merge Request Creation

Create or assign an issue to yourself at the Issue Board Page, add the appropriate labels, and move the issue to “in progress”.

Create a merge request based on that issue using the “Create Merge Request” button on the issue page.

Installation

Note: ARLIN has only been tested on Ubuntu 18.04 and Python 3.9.

Clone the repository

git clone https://gitlab.mitre.org/advxai/arlin.git

Install poetry

curl -sSL https://install.python-poetry.org | python3 -

Note: Don’t forget to add poetry to your path.

export PATH="$HOME/.local/bin:$PATH"

Install required packages
```
cd arlin
poetry shell
poetry install
```
Note: To re-enter the environment after this step, run poetry shell.

Using Pre-commit (Highly Recommended)

If you’d like, you can install pre-commit to run linting and code-formatting before you are able to commit. This will ensure that you pass this portion of the remote pipelines when you push to your merge request.

pre-commit install

Now, every time you try to commit, your code that you have staged will be linted by flake8 and auto-formatted by black. If the linting doesn’t pass pre-commit, it will tell you, and you’ll have to make those changes before committing those files. If black autoformats your code during pre-commit, you can view those changes and then you’ll have to stage them. Then you can commit and push.

Pre-commit can also be run manually on all files without having to commit.

pre-commit run --all-files

Running Unit Tests

There are also unit tests that need to be passed, and to make sure you are passing those locally (before pushing to your remote branch and running the pipeline) you can run the following command in the root directory:

pytest tests/

This will run all of the tests within the tests/ directory.

Adding Packages & Modules

If you add a package or module, make sure to create a unit test for it and preferably all classes and functions within it. The tests are within the tests/ directory and should be named as test_X.py where X is the file you are testing. Try to adhere to this standard when creating new packages, modules, classes, and functions.