From 054bba9edc2127360b3416fad28e20b9fb4c378e Mon Sep 17 00:00:00 2001 From: David Garcia Quintas Date: Thu, 21 Sep 2017 14:04:55 -0700 Subject: [PATCH] More docs --- tools/github/pr_latency.py | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/tools/github/pr_latency.py b/tools/github/pr_latency.py index e773bda37ab..5d635835e54 100644 --- a/tools/github/pr_latency.py +++ b/tools/github/pr_latency.py @@ -13,7 +13,20 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Measure the time between PR creation and completion of all tests""" +"""Measure the time between PR creation and completion of all tests. + +You'll need a github API token to avoid being rate-limited. See +https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/ + +This script goes over the most recent 100 pull requests. For PRs with a single +commit, it uses the PR's creation as the initial time; othewise, it uses the +date of the last commit. This is somewhat fragile, and imposed by the fact that +GitHub reports a PR's updated timestamp for any event that modifies the PR (e.g. +comments), not just the addition of new commits. + +In addition, it ignores latencies greater than five hours, as that's likely due +to a manual re-run of tests. +""" from __future__ import absolute_import from __future__ import division @@ -111,9 +124,13 @@ def get_status_data(statuses_url, system): def build_args_parser(): import argparse parser = argparse.ArgumentParser() - parser.add_argument('--format', type=str, choices=['human', 'csv'], default='human') - parser.add_argument('--system', type=str, choices=['jenkins', 'kokoro'], required=True) - parser.add_argument('--token', type=str, default='') + parser.add_argument('--format', type=str, choices=['human', 'csv'], + default='human', + help='Output format: are you a human or a machine?') + parser.add_argument('--system', type=str, choices=['jenkins', 'kokoro'], + required=True, help='Consider only the given CI system') + parser.add_argument('--token', type=str, default='', + help='GitHub token to use its API with a higher rate limit') return parser