cq/landmines/README.md

Landmines let anyone force the CQ build slaves to clean their out directories.

## Using Landmines
If you want to use a landmine to trigger the bots to clean themselves,
then go to continuous-tests/cq/landmines (the directory this file is in) and
bump the number of the landmine file.
For instance, if there is currently a 'landmine.6' file, create 'landmine.7'.
The CQ will only care about the landmine with the largest number, regardless
of how many landmine files there are.

In the landmine file, add a quick note explaining why a landmine is necessary,
and add a bug number if there is one. This part is purely documentation, but
it is nice to have.

Then, commit your change with the new/updated landmine file.

The next time the CQ runs, the builder then checks if
~/landmines/landmine.<number>/<manifest_branch> exists.
If it already exists, then the builder continues normally.
If it does not exists, the builder runs:
   `make clean` && `touch ~/landmines/landmine.<number>/<manifest_branch>`
This cleans out the $ROOT/out/ directory and all $ROOT/chromium/src/out_*
directories, and then records that the landmine has been processed.

## Landmine File Format
A landmine file must be located inside continous-tests/cq/landmines
A landmine file must have a name of the format: landmine.<number>
Examples:
  continuous-tests/cq/landmines/landmine.1
  continuous-tests/cq/landmines/landmine.23
  continuous-tests/cq/landmines/landmine.9999

## Landmine File Contents
The contents of a landmine file do not affect the behaviour of a landmine
in anyway. However, it is a convenient place to document why a landmine
was needed. A short description and a bug # are usually good to include.

## Landmine History
Each slave keeps track of which landmines it has already seen in its
own ~/landmines directory. Each time a slave sees a new landmine,
it adds a ~/landmines/<landmine>/<manifest_branch> file to the folder,
to indicate it saw <landmine> and triggered a clean. Since the CQ slaves keep
separate checkouts for each manifest branch, the history needs to include
<manifest_branch>.