21
21
# The ratio of "requests remaining" to "total request quota" below which this
22
22
# script should refuse to interact with the GitHub.com API
23
23
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
25
25
# to be actively mirrored by the preview server
26
26
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
29
29
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
31
31
# should automatically receive previews
32
32
#
33
33
# https://developer.github.com/v4/enum/commentauthorassociation/ (equivalent
@@ -105,12 +105,12 @@ def get_pull_requests(self, updated_since):
105
105
)
106
106
107
107
logger .info (
108
- 'Searching for pull requests updated since %s' , window_start
108
+ 'Searching for Pull Requests updated since %s' , window_start
109
109
)
110
110
111
111
data = gh_request ('GET' , url )
112
112
113
- logger .info ('Found %d pull requests ' , len (data ['items' ]))
113
+ logger .info ('Found %d Pull Requests ' , len (data ['items' ]))
114
114
115
115
if data ['incomplete_results' ]:
116
116
raise Exception ('Incomplete results' )
@@ -124,7 +124,7 @@ def add_label(self, pull_request, name):
124
124
self ._host , self ._github_project , number
125
125
)
126
126
127
- logger .info ('Adding label "%s" to pull request #%d' , name , number )
127
+ logger .info ('Adding label "%s" to Pull Request #%d' , name , number )
128
128
129
129
gh_request ('POST' , url , {'labels' : [name ]})
130
130
@@ -154,19 +154,19 @@ def create_deployment(self, pull_request, revision):
154
154
url = '{}/repos/{}/deployments' .format (
155
155
self ._host , self ._github_project
156
156
)
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
159
159
# 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"
161
161
environment = 'gh-{}' .format (pull_request ['number' ])
162
162
163
- logger .info ('Creating deployment for "%s"' , revision )
163
+ logger .info ('Creating Deployment for "%s"' , revision )
164
164
165
165
return gh_request ('POST' , url , {
166
166
'ref' : revision ,
167
167
'environment' : environment ,
168
168
'auto_merge' : False ,
169
- # Pull request previews are created regardless of GitHub Commit
169
+ # Pull Request previews are created regardless of GitHub Commit
170
170
# Status Checks, so Status Checks should be ignored when creating
171
171
# GitHub Deployments.
172
172
'required_contexts' : []
@@ -256,9 +256,9 @@ def is_deployed(host, deployment):
256
256
return response .text .strip () == deployment ['sha' ]
257
257
258
258
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
260
260
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 .'''
262
262
263
263
project = Project (host , github_project )
264
264
remote = Remote (github_project )
@@ -268,7 +268,7 @@ def synchronize(host, github_project, window):
268
268
)
269
269
270
270
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 )
272
272
273
273
refspec_labeled = 'prs-labeled-for-preview/{number}' .format (
274
274
** pull_request
@@ -281,7 +281,7 @@ def synchronize(host, github_project, window):
281
281
revision_open = remote .get_revision (refspec_open )
282
282
283
283
if should_be_mirrored (pull_request ):
284
- logger .info ('Pull request should be mirrored' )
284
+ logger .info ('Pull Request should be mirrored' )
285
285
286
286
if not has_label (pull_request ):
287
287
project .add_label (pull_request , LABEL )
@@ -301,7 +301,7 @@ def synchronize(host, github_project, window):
301
301
pull_request , revision_latest
302
302
)
303
303
else :
304
- logger .info ('Pull request should not be mirrored' )
304
+ logger .info ('Pull Request should not be mirrored' )
305
305
306
306
if not has_label (pull_request ) and revision_labeled != None :
307
307
remote .delete_ref (refspec_labeled )
@@ -310,8 +310,8 @@ def synchronize(host, github_project, window):
310
310
remote .delete_ref (refspec_open )
311
311
312
312
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
315
315
reached.'''
316
316
317
317
project = Project (host , github_project )
@@ -327,7 +327,7 @@ def detect(host, github_project, target, timeout):
327
327
logger .info ('Deployment environment is unrecognized. Exiting.' )
328
328
return
329
329
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 (
331
331
timeout , deployment ['environment' ], target
332
332
)
333
333
logger .info (message )
@@ -347,26 +347,50 @@ def detect(host, github_project, target, timeout):
347
347
logger .info (json .dumps (result , indent = 2 ))
348
348
349
349
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
+ )
351
356
parser .add_argument (
352
357
'--host' , required = True , help = 'the location of the GitHub API server'
353
358
)
354
359
parser .add_argument (
355
- '--github-project' , required = True ,
360
+ '--github-project' ,
361
+ required = True ,
356
362
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")'''
358
364
)
359
365
subparsers = parser .add_subparsers (title = 'subcommands' )
360
366
361
367
parser_sync = subparsers .add_parser (
362
368
'synchronize' , help = synchronize .__doc__
363
369
)
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
+ )
365
378
parser_sync .set_defaults (func = synchronize )
366
379
367
380
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
+ )
370
394
parser_detect .set_defaults (func = detect )
371
395
372
396
values = dict (vars (parser .parse_args ()))
0 commit comments