github.com/gunjan5/docker@v1.8.2/project/REVIEWING.md (about)

     1  Pull request reviewing process
     2  ==============================
     3  
     4  # Labels
     5  
     6  Labels are carefully picked to optimize for:
     7  
     8   - Readability: maintainers must immediately know the state of a PR
     9   - Filtering simplicity: different labels represent many different aspects of
    10     the reviewing work, and can even be targetted at different maintainers groups.
    11  
    12  A pull request should only be attributed labels documented in this section: other labels that may
    13  exist on the repository should apply to issues.
    14  
    15  ## DCO labels
    16  
    17   * `dco/no`: automatically set by a bot when one of the commits lacks proper signature
    18  
    19  ## Status labels
    20  
    21   * `status/0-triage`
    22   * `status/1-design-review`
    23   * `status/2-code-review`
    24   * `status/3-docs-review`
    25   * `status/4-ready-to-merge`
    26  
    27  Special status labels:
    28  
    29   * `status/needs-attention`: calls for a collective discussion during a review session
    30  
    31  ## Specialty group labels
    32  
    33  Those labels are used to raise awareness of a particular specialty group, either because we need
    34  help in reviewing the PR, or because of the potential impact of the PR on their work:
    35  
    36   * `group/distribution`
    37   * `group/networking`
    38   * `group/security`
    39   * `group/windows`
    40  
    41  ## Impact labels (apply to merged pull requests)
    42  
    43   * `impact/api`
    44   * `impact/changelog`
    45   * `impact/cli`
    46   * `impact/dockerfile`
    47   * `impact/deprecation`
    48  
    49  # Workflow
    50  
    51  An opened pull request can be in 1 of 5 distinct states, for each of which there is a corresponding
    52  label that needs to be applied.
    53  
    54  ## Triage - `status/0-triage`
    55  
    56  Maintainers are expected to triage new incoming pull requests by removing the `status/0-triage`
    57  label and adding the correct labels (e.g. `status/1-design-review`) before any other interaction
    58  with the PR. The starting label may potentially skip some steps depending on the kind of pull
    59  request: use your best judgement.
    60  
    61  Maintainers should perform an initial, high-level, overview of the pull request before moving it to
    62  the next appropriate stage:
    63  
    64   - Has DCO
    65   - Contains sufficient justification (e.g., usecases) for the proposed change
    66   - References the Github issue it fixes (if any) in the commit or the first Github comment
    67  
    68  Possible transitions from this state:
    69  
    70   * Close: e.g., unresponsive contributor without DCO
    71   * `status/1-design-review`: general case
    72   * `status/2-code-review`: e.g. trivial bugfix
    73   * `status/3-docs-review`: non-proposal documentation-only change
    74  
    75  ## Design review - `status/1-design-review`
    76  
    77  Maintainers are expected to comment on the design of the pull request.  Review of documentation is
    78  expected only in the context of design validation, not for stylistic changes.
    79  
    80  Ideally, documentation should reflect the expected behavior of the code.  No code review should
    81  take place in this step.
    82  
    83  There are no strict rules on the way a design is validated: we usually aim for a consensus,
    84  although a single maintainer approval is often sufficient for obviously reasonable changes. In
    85  general, strong disagreement expressed by any of the maintainers should not be taken lightly.
    86  
    87  Once design is approved, a maintainer should make sure to remove this label and add the next one.
    88  
    89  Possible transitions from this state:
    90  
    91   * Close: design rejected
    92   * `status/2-code-review`: general case
    93   * `status/3-docs-review`: proposals with only documentation changes
    94  
    95  ## Code review - `status/2-code-review`
    96  
    97  Maintainers are expected to review the code and ensure that it is good quality and in accordance
    98  with the documentation in the PR.
    99  
   100  New testcases are expected to be added. Ideally, those testcases should fail when the new code is
   101  absent, and pass when present. The testcases should strive to test as many variants, code paths, as
   102  possible to ensure maximum coverage.
   103  
   104  Changes to code must be reviewed and approved (LGTM'd) by a minimum of two code maintainers. When
   105  the author of a PR is a maintainer, he still needs the approval of two other maintainers.
   106  
   107  Once code is approved according to the rules of the subsystem, a maintainer should make sure to
   108  remove this label and add the next one. If documentation is absent but expected, maintainers should
   109  ask for documentation and move to status `status/3-docs-review` for docs maintainer to follow.
   110  
   111  Possible transitions from this state:
   112  
   113   * Close
   114   * `status/1-design-review`: new design concerns are raised
   115   * `status/3-docs-review`: general case
   116   * `status/4-ready-to-merge`: change not impacting documentation
   117  
   118  ## Docs review - `status/3-docs-review`
   119  
   120  Maintainers are expected to review the documentation in its bigger context, ensuring consistency,
   121  completeness, validity, and breadth of coverage across all existing and new documentation.
   122  
   123  They should ask for any editorial change that makes the documentation more consistent and easier to
   124  understand.
   125  
   126  Changes and additions to docs must be reviewed and approved (LGTM'd) by a minimum of two docs
   127  sub-project maintainers. If the docs change originates with a docs maintainer, only one additional
   128  LGTM is required (since we assume a docs maintainer approves of their own PR).
   129  
   130  Once documentation is approved (see below), a maintainer should make sure to remove this label and
   131  add the next one.
   132  
   133  Possible transitions from this state:
   134  
   135   * Close
   136   * `status/1-design-review`: new design concerns are raised
   137   * `status/2-code-review`: requires more code changes
   138   * `status/4-ready-to-merge`: general case
   139  
   140  ## Merge - `status/4-ready-to-merge`
   141  
   142  Maintainers are expected to merge this pull request as soon as possible. They can ask for a rebase
   143  or carry the pull request themselves.
   144  
   145  Possible transitions from this state:
   146  
   147   * Merge: general case
   148   * Close: carry PR
   149  
   150  After merging a pull request, the maintainer should consider applying one or multiple impact labels
   151  to ease future classification:
   152  
   153   * `impact/api` signifies the patch impacted the remote API
   154   * `impact/changelog` signifies the change is significant enough to make it in the changelog
   155   * `impact/cli` signifies the patch impacted a CLI command
   156   * `impact/dockerfile` signifies the patch impacted the Dockerfile syntax
   157   * `impact/deprecation` signifies the patch participates in deprecating an existing feature
   158  
   159  ## Close
   160  
   161  If a pull request is closed it is expected that sufficient justification will be provided. In
   162  particular, if there are alternative ways of achieving the same net result then those needs to be
   163  spelled out. If the pull request is trying to solve a use case that is not one that we (as a
   164  community) want to support then a justification for why should be provided.
   165  
   166  The number of maintainers it takes to decide and close a PR is deliberately left unspecified. We
   167  assume that the group of maintainers is bound by mutual trust and respect, and that opposition from
   168  any single maintainer should be taken into consideration. Similarly, we expect maintainers to
   169  justify their reasoning and to accept debating.
   170  
   171  # Escalation process
   172  
   173  Despite the previously described reviewing process, some PR might not show any progress for various
   174  reasons:
   175  
   176   - No strong opinion for or against the proposed patch
   177   - Debates about the proper way to solve the problem at hand
   178   - Lack of consensus
   179   - ...
   180  
   181  All these will eventually lead to stalled PR, where no apparent progress is made across several
   182  weeks, or even months.
   183  
   184  Maintainers should use their best judgement and apply the `status/needs-attention` label. It must
   185  be used sparingly, as each PR with such label will be discussed by a group of maintainers during a
   186  review session. The goal of that session is to agree on one of the following outcomes for the PR:
   187  
   188   * Close, explaining the rationale for not pursuing further
   189   * Continue, either by pushing the PR further in the workflow, or by deciding to carry the patch
   190     (ideally, a maintainer should be immediately assigned to make sure that the PR keeps continued
   191     attention)
   192   * Escalate to Solomon by formulating a few specific questions on which his answers will allow
   193     maintainers to decide.