Skip to content
This repository was archived by the owner on Mar 19, 2021. It is now read-only.

Commit c49d6bc

Browse files
committed
Improve documentation
1 parent 8812907 commit c49d6bc

File tree

1 file changed

+50
-26
lines changed

1 file changed

+50
-26
lines changed

tools/ci/pr_preview.py

Lines changed: 50 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,13 @@
2121
# The ratio of "requests remaining" to "total request quota" below which this
2222
# script should refuse to interact with the GitHub.com API
2323
API_RATE_LIMIT_THRESHOLD = 0.2
24-
# The GitHub Pull Request label which indicates that a pull request is expected
24+
# The GitHub Pull Request label which indicates that a Pull Request is expected
2525
# to be actively mirrored by the preview server
2626
LABEL = 'pull-request-has-preview'
27-
# The number of seconds to wait between attempts to verify that a deployment
28-
# has occurred
27+
# The number of seconds to wait between attempts to verify that a submission
28+
# preview is available on the Pull Request preview server
2929
POLLING_PERIOD = 5
30-
# Pull requests from authors with the following associations to the project
30+
# Pull Requests from authors with the following associations to the project
3131
# should automatically receive previews
3232
#
3333
# https://developer.github.com/v4/enum/commentauthorassociation/ (equivalent
@@ -105,12 +105,12 @@ def get_pull_requests(self, updated_since):
105105
)
106106

107107
logger.info(
108-
'Searching for pull requests updated since %s', window_start
108+
'Searching for Pull Requests updated since %s', window_start
109109
)
110110

111111
data = gh_request('GET', url)
112112

113-
logger.info('Found %d pull requests', len(data['items']))
113+
logger.info('Found %d Pull Requests', len(data['items']))
114114

115115
if data['incomplete_results']:
116116
raise Exception('Incomplete results')
@@ -124,7 +124,7 @@ def add_label(self, pull_request, name):
124124
self._host, self._github_project, number
125125
)
126126

127-
logger.info('Adding label "%s" to pull request #%d', name, number)
127+
logger.info('Adding label "%s" to Pull Request #%d', name, number)
128128

129129
gh_request('POST', url, {'labels': [name]})
130130

@@ -154,19 +154,19 @@ def create_deployment(self, pull_request, revision):
154154
url = '{}/repos/{}/deployments'.format(
155155
self._host, self._github_project
156156
)
157-
# The pull request preview system only exposes one deployment for a
158-
# given pull request. Identifying the deployment by the pull request
157+
# The Pull Request preview system only exposes one Deployment for a
158+
# given Pull Request. Identifying the Deployment by the Pull Request
159159
# number ensures that GitHub.com automatically responds to new
160-
# deployments by designating prior deployments as "inactive"
160+
# Deployments by designating prior Deployments as "inactive"
161161
environment = 'gh-{}'.format(pull_request['number'])
162162

163-
logger.info('Creating deployment for "%s"', revision)
163+
logger.info('Creating Deployment for "%s"', revision)
164164

165165
return gh_request('POST', url, {
166166
'ref': revision,
167167
'environment': environment,
168168
'auto_merge': False,
169-
# Pull request previews are created regardless of GitHub Commit
169+
# Pull Request previews are created regardless of GitHub Commit
170170
# Status Checks, so Status Checks should be ignored when creating
171171
# GitHub Deployments.
172172
'required_contexts': []
@@ -256,9 +256,9 @@ def is_deployed(host, deployment):
256256
return response.text.strip() == deployment['sha']
257257

258258
def synchronize(host, github_project, window):
259-
'''Inspect all pull requests which have been modified in a given window of
259+
'''Inspect all Pull Requests which have been modified in a given window of
260260
time. Add or remove the "preview" label and update or delete the relevant
261-
git refs according to the status of each pull request.'''
261+
git refs according to the status of each Pull Request.'''
262262

263263
project = Project(host, github_project)
264264
remote = Remote(github_project)
@@ -268,7 +268,7 @@ def synchronize(host, github_project, window):
268268
)
269269

270270
for pull_request in pull_requests:
271-
logger.info('Processing pull request #%(number)d', pull_request)
271+
logger.info('Processing Pull Request #%(number)d', pull_request)
272272

273273
refspec_labeled = 'prs-labeled-for-preview/{number}'.format(
274274
**pull_request
@@ -281,7 +281,7 @@ def synchronize(host, github_project, window):
281281
revision_open = remote.get_revision(refspec_open)
282282

283283
if should_be_mirrored(pull_request):
284-
logger.info('Pull request should be mirrored')
284+
logger.info('Pull Request should be mirrored')
285285

286286
if not has_label(pull_request):
287287
project.add_label(pull_request, LABEL)
@@ -301,7 +301,7 @@ def synchronize(host, github_project, window):
301301
pull_request, revision_latest
302302
)
303303
else:
304-
logger.info('Pull request should not be mirrored')
304+
logger.info('Pull Request should not be mirrored')
305305

306306
if not has_label(pull_request) and revision_labeled != None:
307307
remote.delete_ref(refspec_labeled)
@@ -310,8 +310,8 @@ def synchronize(host, github_project, window):
310310
remote.delete_ref(refspec_open)
311311

312312
def detect(host, github_project, target, timeout):
313-
'''Manage the status of a GitHub deployment by polling the pull request
314-
preview website until the deployment is complete or a timeout is
313+
'''Manage the status of a GitHub Deployment by polling the Pull Request
314+
preview website until the Deployment is complete or a timeout is
315315
reached.'''
316316

317317
project = Project(host, github_project)
@@ -327,7 +327,7 @@ def detect(host, github_project, target, timeout):
327327
logger.info('Deployment environment is unrecognized. Exiting.')
328328
return
329329

330-
message = 'Waiting up to {} seconds for deployment {} to be available on {}'.format(
330+
message = 'Waiting up to {} seconds for Deployment {} to be available on {}'.format(
331331
timeout, deployment['environment'], target
332332
)
333333
logger.info(message)
@@ -347,26 +347,50 @@ def detect(host, github_project, target, timeout):
347347
logger.info(json.dumps(result, indent=2))
348348

349349
if __name__ == '__main__':
350-
parser = argparse.ArgumentParser()
350+
parser = argparse.ArgumentParser(
351+
description='''Synchronize the state of a GitHub.com project with the
352+
underlying git repository in order to support a externally-hosted
353+
Pull Request preview system. Communicate the state of that system
354+
via GitHub Deployments associated with each Pull Request.'''
355+
)
351356
parser.add_argument(
352357
'--host', required=True, help='the location of the GitHub API server'
353358
)
354359
parser.add_argument(
355-
'--github-project', required=True,
360+
'--github-project',
361+
required=True,
356362
help='''the GitHub organization and GitHub project name, separated by
357-
a forward slash (e.g. "web-platform-tests/wpt")'''
363+
a forward slash (e.g. "web-platform-tests/wpt")'''
358364
)
359365
subparsers = parser.add_subparsers(title='subcommands')
360366

361367
parser_sync = subparsers.add_parser(
362368
'synchronize', help=synchronize.__doc__
363369
)
364-
parser_sync.add_argument('--window', type=int, required=True)
370+
parser_sync.add_argument(
371+
'--window',
372+
type=int,
373+
required=True,
374+
help='''the number of seconds prior to the current moment within which
375+
to search for GitHub Pull Requests. Any Pull Requests updated in
376+
this time frame will be considered for synchronization.'''
377+
)
365378
parser_sync.set_defaults(func=synchronize)
366379

367380
parser_detect = subparsers.add_parser('detect', help=detect.__doc__)
368-
parser_detect.add_argument('--target', required=True)
369-
parser_detect.add_argument('--timeout', type=int, required=True)
381+
parser_detect.add_argument(
382+
'--target',
383+
required=True,
384+
help='''the URL of the website to which submission previews are
385+
expected to become available'''
386+
)
387+
parser_detect.add_argument(
388+
'--timeout',
389+
type=int,
390+
required=True,
391+
help='''the number of seconds to wait for a submission preview to
392+
become available before reporting a GitHub Deployment failure'''
393+
)
370394
parser_detect.set_defaults(func=detect)
371395

372396
values = dict(vars(parser.parse_args()))

0 commit comments

Comments
 (0)