Contributor Guidelines

Contributor Guidelines

Contributing Documentation Changes

You were confused about our documentation? You ran into a pitfall that others also might run into? Help us making the Marathon documentation great.

The documentation that is published here actually gets generated from what is found in the docs directory.

If you simply want to correct a spelling mistake or improve the wording of a sentence, you can browse the mark down files here and use the edit button above the markup. That will make it easy to create a pull request that will be reviewed by us.

If want to contribute a larger improvement to our documentation:

Please rebase your pull requests on top of the current master using git fetch origin && git rebase origin/master, and squash your changes to a single commit as described here. Yes, we want you to rewrite history - the branch on which you are implementing your changes is only meant for this pull request. You can either rebase before or after you squash your commits, depending on how you'd like to resolve potential merge conflicts. The idea behind is that we don't want an arbitrary number of commits for one pull request, but exactly one commit. This commit should be easy to merge onto master, therefore we ask you to rebase to master.

After you pull request has been accepted, there is still some manual work that we need to do to publish that documentation. But don't worry, we will do that for you.

Getting Started with Code Changes

Maybe you already have a bugfix or enhancement in mind. If not, there are a number of relatively approachable issues with the label "good first issue".

JIRA Issues (Suggesting Bugs and Improvements)

As a general rule, before any change is made to Marathon, a JIRA ticket is filed for bugs, or for proposed improvements. As a guideline, an improvement ticket should include the following:

As the Marathon product team, we don't add new features to the project without discussing the impact and viability of the proposed changes with each other, first. Creating a JIRA before submitting a code change sets the stage for this necessary discussion to happen, consensus on direction to be achieved, ideally before too much effort is spent coding it.

If a change isn't discussed before the code is submitted, there is a higher chance there will be some unconsidered side-effect of the change, or that the change is not in alignment with the long-term vision of Marathon.

Sometimes, we are overwhelmed by the never ending sea of JIRA. If you submit an issue, and don't feel it is getting the level of attention that it should, please find us in the #marathon channel on the Mesos community Slack.

Backporting Policy

All development (new features and bug fixes) are made, first, to the master branch.

If code is heavily refactored but the behavior has not been changed, these patches are generally not backported unless it will help reduce merge conflicts in the future.

Bugs are backported to the current supported versions of Marathon. Historically, this usually tends to be the current stable release, plus the past 2 major releases. (IE, if 1.5.6 is the last stable release, then 1.4.x and 1.3.x would also receive the fix).

New features are rarely backported; when they are, they are backported to the latest stable version of Marathon. Major new features are definitely not backported.

Submitting Code Changes to Marathon

  1. A GitHub pull request is the preferred way of submitting code changes.

  2. If a JIRA issue doesn't already exist, please open one for the proposed change in behavior (see the section above, "JIRA Issues").

  3. Open up a discussion about the JIRA ticket (ideally, in the comments section, but, also in the #marathon channel). Seek to get buy-off and consensus on the direction before making the change.

  4. Please rebase your pull requests on top of the current master, as needed, to integrate upstream changes and resolve conflicts. You can squash your commits if it helps resolve potential merge conflicts. When your PR is merged, it will be squashed to a single commit.

  5. If you are targeting to get something fixed for an older release of Marathon, fix it on master, first. If it is already fixed in master, first, find out why. See our "Backporting Policy" above.

  6. Please include in your commit message the line "JIRA Issues: MARATHON-1234", where MARATHON-1234 is the JIRA issue mentioned in item 2 above. This helps reviewers better understand the context of the change.

  7. If you change modifies the public API or behavior, then the project documentation must be updated (in the same pull request). Further, notes about the change should be specified in

  8. Pull requests should include appropriate additions to the unit test suite (see "Test Guidelines", below). If the change is a bugfix, then one of the added tests should fail without the fix.

  9. Compile your code prior to committing. We would like the result of our automatic code formatters to be included in the commit as to not produce a dirty work tree after fresh checkout and first compile.

  10. Run, at the very least, all unit tests (sbt test). Integration tests can also be run using the supplied ./bin/ script (requires docker).

Test Guidelines

General guidelines


Our testing guidelines regarding fixtures are as follows:

Running Integration Tests


Running integration tests requires that several components are installed and available locally:

Note that the integration test suites launch and use a local, embedded, version of Zookeeper.

Installing Mesos

Marathon integration tests require an installation of Mesos in order to run. The Mesos executables, including mesos, mesos-master, and mesos-agent must be included in the PATH. Further, the environment variable MESOS_NATIVE_JAVA_LIBRARY should be set to the path of libmesos.dylib /

Installing from source, manually

You can install Mesos from source, manually, by following the instructions here

Installing from source using

To install Mesos from source, you can use the provided scripts/ script. Please read the header of the script for pre-requisite steps.

scripts/ --latest

This will take 30 minutes or so to install on a modern processor.

Installing from Homebrew (OS X, fastest)

You can install a version of Mesos from Homebrew. The Homebrew Mesos version often lags behind the latest version of Mesos. Most of the time, however, this is not a problem.

Running Tests

Some integration tests are disabled by default (references WhenEnvSet). Setting these environment variables will enable them.


To run all of the integration tests using sbt:

sbt integration:test

To run a single integration test:

$ sbt

marathon(...)> set testOptions in Test := Nil


marathon(...)> test-only mesosphere.marathon.integration.AppDeployIntegrationTest -- -oF

Source Files


Style Checker

Executing the test task in SBT also invokes the style checker. Some basic style issues will cause the build to fail: While you should fix all of these, you can disable them if it is a false positive with // linter:ignore Arg as listed here: Linter.

Type Annotations

Scala has a powerful type inference engine. The reason for including more type annotations than are required to make the program compile is to increase readability.


Assigning the null value should be avoided. It's usually only necessary when calling into a Java library that ascribes special semantics to null. Prefer scala.Option in all other cases.

Higher Order Functions

GOOD: * 2) { item =>
  item -> f(item)
} {
  case a: A if a.isEmpty => f(a)
  case a: A              => g(a)
  case b: B              => h(b)
  case other: _          => e(other)

Note: match expressions must be exhaustive unless the higher-order function signature explicitly expects a PartialFunction[_, _] as in collect, and collectFirst.

for {
  x <- xs
  y <- x
  z <- y
} yield z


xs map f // dangerous if more infix operators follow => f(item)) // use curlies
xs.flatMap(_.flatMap( // replace with a for comprehension