Explain project roles and how to attain them (#2377)

* Explain project roles and how to attain them

* Update reviewing guide with prow commands

REVIEWING.md

@@ -5,24 +5,21 @@ pull requests (PRs). It is intended to outline the lightweight process that
 we’ll use for now. It’s assumed that we’ll operate on good faith for now in
 situations for which process is not specified.
 
-PRs may only be merged after the following criteria are met:
+PRs are automatically merged after the following criteria are met:
 
-1. It has been 'LGTM'-ed by 2 different reviewers
-1. It has all appropriate corresponding documentation and testcases
-1. The master build is passing. Do not merge a PR unless it is fixing the broken build.
+1. It has the `lgtm` label applied. This label is automatically removed when
+    the commits in the PR are modified. It can be added with `/lgtm` and removed
+    with `/lgtm cancel`.
+1. It has the `approved` label applied. This label is "sticky" and remains
+    even after subsequent changes are made to the commits in the PR. It can be
+    added with `/approve` and removed with `/approve cancel`.
+1. The CI checks are all passing.
 
-## LGTMs
+## Holds
 
-When a reviewer deems a PR good enough to merge, they should add a comment to the PR
-thread that simply reads 'LGTM'. If they do not deem it ready for merge,
-they should add comments -- either inline or on the PR thread -- that indicate
-changes they believe should be made before merge.
-
-## Vetoing
-
-If a reviewer decides that a PR should not be merged in its current state,
-even if it has 2 'LGTM' approvals from others, they should mark that PR with
-`do-not-merge` label.
+If a PR should not be merged in its current state,
+even once it has the `lgtm` and `approved` labels from others, mark that PR with
+`do-not-merge/hold` label using the `/hold` command.
 
 This label should only be used by a reviewer when that person believes there
 is a fundamental problem with the PR. The reviewer should summarize that problem

docs/contribute/ladder.md

@@ -0,0 +1,94 @@
+---
+title: Contribution Ladder
+layout: docwithnav
+---
+
+There are many ways to contribute to the Service Catalog project. Here are the
+various levels of involvement and how to get there!
+
+In general we try to follow the [standard Kubernetes roles](https://github.com/kubernetes/community/blob/master/community-membership.md).
+
+## User
+Try out Service Catalog, either on development cluster like Minikube or in the 
+cloud. Let us know how it goes!
+
+  * Open an issue for any gaps in the documentation that you encounter.
+  * File a bug when unexpected things happen.
+  * Take a look at some of our open proposals and provide feedback.
+  * Answer questions of other users in the community.
+
+## Member
+Project members are people who use Service Catalog and are interested in contributing
+futher.
+
+* Assign issues to yourself.
+* Verify that a pull request is safe to run tests against with the `/ok-to-test`
+  command.
+* Review a pull request and apply the `/lgtm` command that signals that it's
+  ready for final approval.
+
+Once you feel ready, ask another member if they would be willing to be a sponsor
+for your [membership request](https://github.com/kubernetes/org/issues/new?template=membership.md&title=REQUEST%3A%20New%20membership%20for%20%3Cyour-GH-handle%3E).
+The best people to ask are those who have reviewed your pull requests in the past.
+When you request membership, make sure to ask for the `kubernetes-incubator` 
+organization.
+
+✅ If you are already a member of the github.com/kubernetes organization, you can
+immediately apply to become a member of github.com/kubernetes-incubator where
+the Service Catalog project lives.
+
+❓If you aren't sure if you are ready, or need help finding sponsors, reach out
+to the current [chairs][chairs].
+
+## Reviewer
+After you have contributed to an area of Service Catalog for a while, you may
+ready help review pull requests either in just that area, or for the entire 
+repository.
+
+Reviewers have an entry in the [OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md)
+file in the repository indicating that they are a good candidate to be 
+automatically assigned or suggested as a reviewer for that area of code 
+(or the entire repository).
+
+❓If you are willing to review PRs in a particular area, submit a PR adding
+your GitHub name to the OWNERS file in the sub-directory of that area in a 
+`reviewers` section.
+
+## Maintainer
+Kubernetes traditionally calls this role "approver".
+
+Maintainers have an approver entry in the [OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md)
+file in the repository indicating that they are an experienced reviewer and
+contributor in a particular area. They are responsible for the final review of 
+a pull request, and signing off that it is ready to merge.
+
+* Review a pull request and apply the final `/approve` command that signals 
+  that the pull request is ready to merge.
+* An approver may decide to apply both the `/lgtm` and `/approve` commands. This
+  sometimes is a good choice for small non-controversial pull requests where
+  there aren't other people who should be consulted first.
+* Our repository is configured to require both the `lgtm` and `approved` labels
+  before merging. 
+
+❓If you feel that you are ready to become a maintainer, reach out to a [chair][chairs]
+and they will help sponsor you. Maintainers are added by a vote amongst the chairs.
+
+See our [charter][charter] for a full list of responsibilities and the voting process.
+
+## Chair
+Chairs are maintainers who also perform extra project management and 
+administrative work for the project such as:
+
+* Facilitating the SIG meetings and recording them.
+* Grooming the backlog.
+* Finding issues that are good for beginners and ensuring that issues are
+  appropriately explained and labeled.
+* Representing the SIG at Kubernetes community standup meetings.
+
+❓If you are interested in becoming a chair, reach out to a [chair][chairs]
+and they will help sponsor you. Chairs are added by a vote amongst the chairs.
+
+See our [charter][charter] for a full list of responsibilities and the voting process.
+
+[charter]: https://github.com/kubernetes/community/blob/master/sig-service-catalog/charter.md
+[chairs]: https://github.com/kubernetes/community/blob/master/sig-service-catalog/README.md#chairs

docs/devguide.md

@@ -5,36 +5,12 @@ layout: docwithnav
 
 ## Overview
 
-This repository is organized as similarly to Kubernetes itself as the developers
-have found possible (or practical). Below is a summary of the repository's
-layout:
+Thank you for deciding to contribute to our project! 💖 We welcome contributors
+from all backgrounds and experience levels. 
 
-    .
-    ├── bin                     # Destination for binaries compiled for linux/amd64 (untracked)
-    ├── build                   # Contains build-related scripts and subdirectories containing Dockerfiles
-    ├── charts                  # Helm charts for deployment
-    │   └── catalog             # Helm chart for deploying the service catalog
-    │   └── ups-broker          # Helm chart for deploying the user-provided service broker
-    ├── cmd                     # Contains "main" Go packages for each service catalog component binary
-    │   └── apiserver           # The service catalog API server service-catalog command
-    │   └── controller-manager  # The service catalog controller manager service-catalog command
-    │   └── service-catalog     # The service catalog binary, which is used to run commands
-    │   └── svcat               # The command-line interface for interacting with kubernetes service-catalog resources
-    ├── contrib                 # Contains examples, non-essential golang source, CI configurations, etc
-    │   └── build               # Dockerfiles for contrib images (example: ups-broker)
-    │   └── cmd                 # Entrypoints for contrib binaries
-    │   └── examples            # Example API resources
-    │   └── hack                # Non-build related scripts
-    │   └── jenkins             # Jenkins configuration
-    │   └── pkg                 # Contrib golang code
-    │   └── travis              # Travis configuration
-    ├── docs                    # Documentation
-    ├── pkg                     # Contains all non-"main" Go packages
-    ├── plugin                  # Plugins for API server
-    ├── test                    # Integration and e2e tests
-    ├── vendor                  # dep-managed dependencies
-    ├── Gopkg.toml              # dep manifest
-    └── Gopkg.lock              # dep lock (autogenerated, do not edit)
+If you are interested in going beyond a single PR, take a look at our 
+[contribution ladder](/contribute/ladder.md) and learn how to become a reviewer, 
+or even a maintainer!
 
 ## Working on Issues
 
@@ -136,6 +112,38 @@ git remote set-url --push upstream no_push
 git remote -v
 ```
 
+## Code Layout
+This repository is organized as similarly to Kubernetes itself as the developers
+have found possible (or practical). Below is a summary of the repository's
+layout:
+
+    .
+    ├── bin                     # Destination for binaries compiled for linux/amd64 (untracked)
+    ├── build                   # Contains build-related scripts and subdirectories containing Dockerfiles
+    ├── charts                  # Helm charts for deployment
+    │   └── catalog             # Helm chart for deploying the service catalog
+    │   └── ups-broker          # Helm chart for deploying the user-provided service broker
+    ├── cmd                     # Contains "main" Go packages for each service catalog component binary
+    │   └── apiserver           # The service catalog API server service-catalog command
+    │   └── controller-manager  # The service catalog controller manager service-catalog command
+    │   └── service-catalog     # The service catalog binary, which is used to run commands
+    │   └── svcat               # The command-line interface for interacting with kubernetes service-catalog resources
+    ├── contrib                 # Contains examples, non-essential golang source, CI configurations, etc
+    │   └── build               # Dockerfiles for contrib images (example: ups-broker)
+    │   └── cmd                 # Entrypoints for contrib binaries
+    │   └── examples            # Example API resources
+    │   └── hack                # Non-build related scripts
+    │   └── jenkins             # Jenkins configuration
+    │   └── pkg                 # Contrib golang code
+    │   └── travis              # Travis configuration
+    ├── docs                    # Documentation
+    ├── pkg                     # Contains all non-"main" Go packages
+    ├── plugin                  # Plugins for API server
+    ├── test                    # Integration and e2e tests
+    ├── vendor                  # dep-managed dependencies
+    ├── Gopkg.toml              # dep manifest
+    └── Gopkg.lock              # dep lock (autogenerated, do not edit)
+
 ## Building
 
 First `cd` to the root of the cloned repository tree.

docsite/_config.yml

@@ -60,4 +60,5 @@ tocs:
   - namespaced-broker-resources
   - catalog-restrictions
   - service-plan-defaults
+  - ladder
   - docs-home # fallthrough, leave this last

docsite/_data/ladder.yml

@@ -0,0 +1,16 @@
+bigheader: "Contribution Ladder"
+abstract: "Going from First PR to Maintainer"
+landing_page: /docs/contribute/ladder/
+toc:
+- docs/contribute/ladder.md
+- title: User
+  path: "#user"
+- title: Member
+  path: "#member"
+- title: Reviewer
+  path: "#reviewer"
+- title: Maintainer
+  path: "#maintainer"
+- title: Chair
+  path: "#chair"
+

docsite/community.md

@@ -27,7 +27,7 @@ cid: community
                   <a href="https://github.com/kubernetes-incubator/service-catalog"><img src="/images/github-logo.png" alt="GitHub" width="150"></a>
                   <p>
                     <a href="https://github.com/kubernetes-incubator/service-catalog">GitHub</a><br/>
-                    <a href="https://github.com/kubernetes-incubator/service-catalog/blob/master/docs/devguide.md">Developer Guide</a><br/>
+                    <a href="/docs/devguide/">Developer Guide</a><br/>
                     <a href="https://github.com/kubernetes-incubator/service-catalog/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22">Issues that Need Help</a><br/>
                   </p>
               </div>