Contributing

Contributions to this repository must pass tests and linting.

Install Contribution Dependencies

Requires Python 3.6+. To avoid interfering with your system’s Python, we recommend using a virtualenv.

Check the Python version:

python3 --version

On Fedora, install Python development requirements:

dnf install -y git python3-devel

On Ubuntu, install Python development requirements:

apt update -y && \
apt install -y software-properties-common && \
apt upgrade -y python-apt && \
add-apt-repository -y ppa:deadsnakes/ppa && \
apt update -y && \
apt upgrade -y gcc python3-dev python3.6-dev libffi-dev libssl-dev git python3-pip
pip3 install setuptools

Install dependencies, preferably in a virtual environment. If you are not in a virtualenv, you may have to use sudo before the following command, or --user after install.

pip3 install --editable '.[dev]'

Optionally install the following tools for linting and interacting with Travis CI:

gem install travis --no-rdoc --no-ri

Spell checking requires enchant. This can be installed on macOS, for example, with Homebrew:

brew install enchant

and on Ubuntu with apt:

apt install -y enchant

Linting Bash requires shellcheck: This can be installed on macOS, for example, with Homebrew:

brew install shellcheck

and on Ubuntu with apt:

apt-get install -y shellcheck

Linting

Install Contribution Dependencies.

Run lint tools:

make lint

These can be run in parallel with:

make lint --jobs --output-sync=target

To fix some lint errors, run the following:

make fix-lint

Tests for this package

To run the full test suite, set environment variables for DC/OS Enterprise installer URLs:

export EE_MASTER_INSTALLER_URL=https://...
export EE_1_9_INSTALLER_URL=https://...
export EE_1_10_INSTALLER_URL=https://...
export EE_1_11_INSTALLER_URL=https://...
export EE_1_12_INSTALLER_URL=https://...
export EE_1_13_INSTALLER_URL=https://...

Download dependencies which are used by the tests:

python admin/download_installers.py

A license key is required for some tests:

cp /path/to/license-key.txt /tmp/license-key.txt

Run pytest:

pytest

To run the tests concurrently, use pytest-xdist. For example:

pytest -n 2

Documentation

Run the following commands to build and open the documentation:

make docs
make open-docs

Reviews

Ask Adam Dangoor if you are unsure who to ask for help from.

CI

Linting and some tests are run on Travis CI. See .travis.yml for details on the limitations. To check if a new change works on CI, unfortunately it is necessary to change .travis.yml to run the desired tests.

Most of the CLI functionality is not covered by automated tests. Changes should take this into consideration.

Rotating license keys

DC/OS Enterprise requires a license key. Mesosphere uses license keys internally for testing, and these expire regularly. A license key is encrypted and used by the Travis CI tests.

To update this link use the following command, after setting the LICENSE_KEY_CONTENTS environment variable.

This command will affect all builds and not just the current branch.

We do not use encrypted secret files in case the contents are shown in the logs.

We do not add an encrypted environment variable to .travis.yml because the license is too large.

travis env set --repo |github-owner|/|github-repository| LICENSE_KEY_CONTENTS $LICENSE_KEY_CONTENTS

Updating the Amazon Web Services credentials

Private credentials for Amazon Web Services are used by Travis CI.

To update the credentials use the following commands, after setting the following environment variables:

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

travis env set --repo |github-owner|/|github-repository| AWS_ACCESS_KEY_ID $AWS_ACCESS_KEY_ID
travis env set --repo |github-owner|/|github-repository| AWS_SECRET_ACCESS_KEY $AWS_SECRET_ACCESS_KEY

Currently credentials are taken from the OneLogin Secure Notes note dcos-e2e integration testing AWS credentials.

Parallel builders

Travis CI has a maximum test run time of 50 minutes. In order to avoid this and to see failures faster, we run multiple builds per commit. We run almost one builder per test. Some tests are grouped as they can run quickly.

Goals

Avoid flakiness

For timeouts, err on the side of a much longer timeout than necessary.

Do not access the web while running tests.

Parallelizable Tests

The tests in this repository and using this harness are slow. This harness must not get in the way of parallelization efforts.

Logging

End to end tests are notoriously difficult to get meaning from. To help with this, an “excessive logging” policy is used here.

Robustness

Narrowing down bugs from end to end tests is hard enough without dealing with the framework’s bugs. This repository aims to maintain high standards in terms of coding quality and quality enforcement by CI is part of that.

Version Policy

This repository aims to work with DC/OS OSS and DC/OS Enterprise master branches. These are moving targets. For this reason, CalVer is used as a date at which the repository is last known to have worked with DC/OS OSS and DC/OS Enterprise is the main versioning use.

Updating vendored packages

Various repositories, such as DC/OS Test Utils and DC/OS Launch are vendored in this repository. To update DC/OS Test Utils or DC/OS Launch:

Update the SHAs in admin/update_vendored_packages.py.

The following creates a commit with changes to the vendored packages:

python admin/update_vendored_packages.py