github.com/dlintw/docker@v1.5.0-rc4/project/MAINTAINERS.md (about)

     1  # The Docker Maintainer manual
     2  
     3  ## Introduction
     4  
     5  Dear maintainer. Thank you for investing the time and energy to help
     6  make Docker as useful as possible. Maintaining a project is difficult,
     7  sometimes unrewarding work. Sure, you will get to contribute cool
     8  features to the project. But most of your time will be spent reviewing,
     9  cleaning up, documenting, answering questions, and justifying design
    10  decisions - while everyone has all the fun! But remember - the quality
    11  of the maintainers' work is what distinguishes the good projects from
    12  the great. So please be proud of your work, even the unglamourous parts,
    13  and encourage a culture of appreciation and respect for *every* aspect
    14  of improving the project - not just the hot new features.
    15  
    16  This document is a manual for maintainers old and new. It explains what
    17  is expected of maintainers, how they should work, and what tools are
    18  available to them.
    19  
    20  This is a living document - if you see something out of date or missing,
    21  speak up!
    22  
    23  ## What is a maintainer's responsibility?
    24  
    25  It is every maintainer's responsibility to:
    26  
    27  1. Expose a clear road map for improving their component.
    28  2. Deliver prompt feedback and decisions on pull requests.
    29  3. Be available to anyone with questions, bug reports, criticism etc.
    30    on their component. This includes IRC, GitHub requests and the mailing
    31    list.
    32  4. Make sure their component respects the philosophy, design and
    33    road map of the project.
    34  
    35  ## How are decisions made?
    36  
    37  Short answer: with pull requests to the Docker repository.
    38  
    39  Docker is an open-source project with an open design philosophy. This
    40  means that the repository is the source of truth for EVERY aspect of the
    41  project, including its philosophy, design, road map, and APIs. *If it's
    42  part of the project, it's in the repo. If it's in the repo, it's part of
    43  the project.*
    44  
    45  As a result, all decisions can be expressed as changes to the
    46  repository. An implementation change is a change to the source code. An
    47  API change is a change to the API specification. A philosophy change is
    48  a change to the philosophy manifesto, and so on.
    49  
    50  All decisions affecting Docker, big and small, follow the same 3 steps:
    51  
    52  * Step 1: Open a pull request. Anyone can do this.
    53  
    54  * Step 2: Discuss the pull request. Anyone can do this.
    55  
    56  * Step 3: Accept (`LGTM`) or refuse a pull request. The relevant maintainers do 
    57  this (see below "Who decides what?")
    58   + Accepting pull requests
    59    - If the pull request appears to be ready to merge, give it a `LGTM`, which
    60      stands for "Looks Good To Me".
    61    - If the pull request has some small problems that need to be changed, make
    62      a comment adressing the issues.
    63    - If the changes needed to a PR are small, you can add a "LGTM once the
    64      following comments are adressed..." this will reduce needless back and
    65      forth.
    66    - If the PR only needs a few changes before being merged, any MAINTAINER can
    67      make a replacement PR that incorporates the existing commits and fixes the
    68      problems before a fast track merge.
    69   + Closing pull requests
    70    - If a PR appears to be abandoned, after having attempted to contact the
    71      original contributor, then a replacement PR may be made.  Once the
    72      replacement PR is made, any contributor may close the original one.
    73    - If you are not sure if the pull request implements a good feature or you
    74      do not understand the purpose of the PR, ask the contributor to provide
    75      more documentation.  If the contributor is not able to adequately explain
    76      the purpose of the PR, the PR may be closed by any MAINTAINER.
    77    - If a MAINTAINER feels that the pull request is sufficiently architecturally
    78      flawed, or if the pull request needs significantly more design discussion
    79      before being considered, the MAINTAINER should close the pull request with
    80      a short explanation of what discussion still needs to be had.  It is
    81      important not to leave such pull requests open, as this will waste both the
    82      MAINTAINER's time and the contributor's time.  It is not good to string a
    83      contributor on for weeks or months, having them make many changes to a PR
    84      that will eventually be rejected.
    85  
    86  ## Who decides what?
    87  
    88  All decisions are pull requests, and the relevant maintainers make
    89  decisions by accepting or refusing pull requests. Review and acceptance
    90  by anyone is denoted by adding a comment in the pull request: `LGTM`.
    91  However, only currently listed `MAINTAINERS` are counted towards the
    92  required majority.
    93  
    94  Docker follows the timeless, highly efficient and totally unfair system
    95  known as [Benevolent dictator for
    96  life](http://en.wikipedia.org/wiki/Benevolent_Dictator_for_Life), with
    97  yours truly, Solomon Hykes, in the role of BDFL. This means that all
    98  decisions are made, by default, by Solomon. Since making every decision
    99  myself would be highly un-scalable, in practice decisions are spread
   100  across multiple maintainers.
   101  
   102  The relevant maintainers for a pull request can be worked out in 2 steps:
   103  
   104  * Step 1: Determine the subdirectories affected by the pull request. This
   105    might be `src/registry`, `docs/source/api`, or any other part of the repo.
   106  
   107  * Step 2: Find the `MAINTAINERS` file which affects this directory. If the
   108    directory itself does not have a `MAINTAINERS` file, work your way up
   109    the repo hierarchy until you find one.
   110  
   111  There is also a `hacks/getmaintainers.sh` script that will print out the 
   112  maintainers for a specified directory.
   113  
   114  ### I'm a maintainer, and I'm going on holiday
   115  
   116  Please let your co-maintainers and other contributors know by raising a pull
   117  request that comments out your `MAINTAINERS` file entry using a `#`.
   118  
   119  ### I'm a maintainer. Should I make pull requests too?
   120  
   121  Yes. Nobody should ever push to master directly. All changes should be
   122  made through a pull request.
   123  
   124  ### Helping contributors with the DCO
   125  
   126  The [DCO or `Sign your work`](
   127  https://github.com/docker/docker/blob/master/CONTRIBUTING.md#sign-your-work)
   128  requirement is not intended as a roadblock or speed bump.
   129  
   130  Some Docker contributors are not as familiar with `git`, or have used a web based
   131  editor, and thus asking them to `git commit --amend -s` is not the best way forward.
   132  
   133  In this case, maintainers can update the commits based on clause (c) of the DCO. The
   134  most trivial way for a contributor to allow the maintainer to do this, is to add
   135  a DCO signature in a Pull Requests's comment, or a maintainer can simply note that
   136  the change is sufficiently trivial that it does not substantivly change the existing
   137  contribution - i.e., a spelling change.
   138  
   139  When you add someone's DCO, please also add your own to keep a log.
   140  
   141  ### Who assigns maintainers?
   142  
   143  Solomon has final `LGTM` approval for all pull requests to `MAINTAINERS` files.
   144  
   145  ### How is this process changed?
   146  
   147  Just like everything else: by making a pull request :)