Document job.runMax

[jzaefferer]

There's currently no docs on what runMax actually does: https://github.com/jquery/testswarm/blob/master/scripts/addjob/README.md#job-information

I noticed this when trying to provide better API docs for node-testswarm, where the runMax option is lacking the same details: https://github.com/jzaefferer/node-testswarm#clientaddjob-options-callback-

@Krinkle can you tell me what the option is supposed to do? I can write the docs then.

[Krinkle]

The documentation there ("how often failed tests should rerun", which I presumably added or is copied from something I wrote) is accurate though not very elaborate.

There's a slightly more elaborate description on the Addjob page:

This is the maximum number of times a run is ran in a user agent. If a run passes
without failures then it is only ran once. If it does not pass, TestSwarm will re-try the run
(up to "Run max" times) for that useragent to avoid error pollution due to time-outs, slow
computers or other unrelated conditions that can cause the server to not receive a success report.

In the database we keep track of completed times (increased in SaverunAction). When a client requests a run to run, it only looks for runs where completed is < max (in most cases completed=0, and it runs it for the first time, but if it did fail, and max > 1, we'll let it distribute to the clients once more).

However, though this works fine from TestSwarm's perspective. If you start aggregating jobs into another workflow (like we do with node-testswarm and Jenkins) it will not wait for the additional runs to complete (see issue #217), as soon as all runs have a status (pass or fail) it invokes the callback and reports back upstream.