github.com/yrj2011/jx-test-infra@v0.0.0-20190529031832-7a2065ee98eb/prow/cmd/tide/README.md (about)

     1  # Tide
     2  
     3  Tide is a [Prow](https://github.com/kubernetes/test-infra/blob/master/prow/README.md)
     4  component for managing a pool of PRs that match a given set of criteria.
     5  It will automatically retest and merge PRs in the pool if they pass tests
     6  against the latest base branch commit.
     7  
     8  Configuration of Tide is located under
     9  [prow/config.yaml](https://github.com/kubernetes/test-infra/blob/master/prow/config.yaml)
    10  file. It consists of two parts:
    11  
    12    * **Specification of PR pools/criteria**:
    13      A set of all PRs Tide keeps track of.
    14      The PRs are periodically checked if they are ready to be merged.
    15      Configured under `tide` key of the configuration file.
    16  
    17    * **Specification of PR tests**:
    18      A set of jobs that are run over each PR before it gets merged.
    19      No job is required to be provided in which case it's enough if a PR has all
    20      relevant labels set. If a set of jobs is specified,
    21      all must succeed (unless a job is configured with `skip_report: true`).
    22      Configured under `presubmits` key of the configuration file.
    23  
    24  ## PR pools
    25  
    26  The set of criteria is specified through the following collection of items:
    27  
    28  ```yaml
    29  tide:
    30    queries:                // List of queries
    31    - repo:                   // org/repo
    32      labels:                 // List of must have labels
    33      missingLabels:          // List of can't have labels
    34      excludedBranches:       // Ignore branches
    35      includedBranches:       // Include-only branches
    36      reviewApprovedRequired: // Github Review approval required
    37    sync_period:            // Sync jobs period
    38    status_update_period:   // PR status update period
    39    merge_method:           // Set to squash, rebase or just merge PR
    40    target_url:             // URL linked to from the details link on the Github status context
    41    pr_status_base_url:     // PR status page
    42    max_goroutines:         // Per-pool parallelism
    43  ```
    44  
    45  Depending on your criteria, some of the items may by omitted.
    46  
    47  See [https://godoc.org/github.com/kubernetes/test-infra/prow/config#Tide](https://godoc.org/github.com/kubernetes/test-infra/prow/config#Tide) for more detail.
    48  
    49  ### General configuration
    50  
    51  The following configuration fields are available:
    52  
    53  * `sync_period`: The field specifies how often Tide will sync jobs with Github. Defaults to 1m.
    54  * `status_update_period`: The field specifies how often Tide will update Github status contexts.
    55     Defaults to the value of `sync_period`.
    56  * `queries`: List of queries (described below).
    57  * `merge_method`: A key/value pair of an `org/repo` as the key and merge method to override
    58     the default method of merge as value. Valid options are `squash`, `rebase`, and `merge`.
    59     Defaults to `merge`.
    60  * `target_url`: URL for tide status contexts.
    61  * `pr_status_base_url`: The base URL for the PR status page. If specified, this URL is used to construct
    62     a link that will be used for the tide status context. It is mutually exclusive with the `target_url` field.
    63  * `max_goroutines`: The maximum number of goroutines spawned inside the component to
    64     handle org/repo:branch pools. Defaults to 20. Needs to be a positive number.
    65  
    66  ### Queries
    67  
    68  The `queries` field specifies a list of queries.
    69  Each query corresponds to a set of **open** PRs as candidates for merging.
    70  It can consist of the following dictionary of fields:
    71  
    72  * `repos`: List of queried repositories.
    73  * `labels`: List of labels any given PR must posses.
    74  * `missingLabels`: List of labels any given PR must not posses.
    75  * `excludedBranches`: List of branches that get excluded when querying the `repos`.
    76  * `includedBranches`: List of branches that get included when querying the `repos`.
    77  * `reviewApprovedRequired`: If set, each PR in the query must have at
    78    least one [approved github pull request
    79    review](https://help.github.com/articles/about-pull-request-reviews/)
    80    present for merge. Defaults to `false`.
    81  
    82  Under the hood, a query constructed from the fields follows rules described in
    83  https://help.github.com/articles/searching-issues-and-pull-requests/.
    84  Therefore every query is just a structured definition of a standard GitHub
    85  search query which can be used to list mergeable PRs.
    86  The field to search token correspondence is based on the following mapping:
    87  
    88  * `repos` -> `repo:org/repo`
    89  * `labels` -> `label:lgtm`
    90  * `missingLabels` -> `-label:do-not-merge`
    91  * `excludedBranches` -> `-branch:dev`
    92  * `includedBranches` -> `branch:master`
    93  * `reviewApprovedRequired` -> `review:approved`
    94  
    95  **Important**: Each query must return a different set of PRs. No two queries are allowed to contain the same PR.
    96  
    97  Every PR that need to be rebased is filtered from the pool before processing
    98  
    99  
   100  ### Context Policy Options
   101  
   102  A PR will be merged when all checks are passing. With this option you can customize
   103  which contexts are required or optional.
   104  
   105  By default, required and optional contexts will be derived from Prow Job Config.
   106  This allows to find if required checks are missing from the github combined status.
   107  
   108  If `branch-protection` config is defined, it can be used to know which test needs
   109  be passing to merge a PR.
   110  
   111  When branch protection is not used, required and optional contexts can be defined
   112  globally, or at the org, repo or branch level.
   113  
   114  If we want to skip unknown checks (ie checks that are not defined in Prow Config), we can set
   115  `skip-unknown-contexts` to true. This option can be set globally or per org,
   116  repo and branch.
   117  
   118  **Important**: If this option is not set and no prow jobs are defined tide will trust the github
   119  combined status and will assume that all checks are required (except tide).
   120  
   121  
   122  ### Example
   123  
   124  ```yaml
   125  tide:
   126    merge_method:
   127      kubeflow/community: squash
   128  
   129    target_url: https://prow.k8s.io/tide.html
   130  
   131    queries:
   132    - repos:
   133      - kubeflow/community
   134      - kubeflow/examples
   135      labels:
   136      - lgtm
   137      - approved
   138      missingLabels:
   139      - do-not-merge
   140      - do-not-merge/hold
   141      - do-not-merge/work-in-progress
   142      - needs-ok-to-test
   143      - needs-rebase
   144  
   145    context_options:
   146      # Use branch protection options to define required and optional contexts
   147      from-branch-protection: true
   148      # Treat unknown contexts as optional
   149      skip-unknown-contexts: true
   150      orgs:
   151        org:
   152          required-contexts:
   153          - "check-required-for-all-repos"
   154          repos:
   155  	  repo:
   156              required-contexts:
   157               - "check-required-for-all-branches"
   158              branches:
   159                branch:
   160                  from-branch-protection: false
   161                  required-contexts:
   162                  - "required_test"
   163                  optional-contexts:
   164                  - "optional_test"
   165  
   166  ```
   167  
   168  **Explanation**: The component starts periodically querying all PRs in `github.com/kubeflow/community` and
   169  `github.com/kubeflow/examples` repositories that have `lgtm` and `approved` labels set
   170  and do not have `do-not-merge`, `do-not-merge/hold`, `do-not-merge/work-in-progress`, `needs-ok-to-test` and `needs-rebase` labels set.
   171  All PRs that conform to the criteria are processed and merged.
   172  The processing itself can include running jobs (e.g. tests) to verify the PRs are good to go.
   173  At the same time all commits in PRs from `github.com/kubeflow/community` repository are squashed before merging.
   174  
   175  ## Presubmits
   176  
   177  Before a PR is merged, Tide ensures that all jobs configured as required (with `skip_report: false`) in the `presubmits` part of the `config.yaml` file
   178  are passing against the latest base branch commit, rerunning the jobs if necessary.
   179  
   180  Semantic of individual fields of the `presubmits` is described in [prow/README.md#how-to-add-new-jobs](https://github.com/kubernetes/test-infra/blob/master/prow/README.md#how-to-add-new-jobs).