-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathmanual.html
747 lines (576 loc) · 27.6 KB
/
manual.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
<!DOCTYPE html>
<html lang=en-us>
<meta charset=utf-8>
<meta name="viewport" content="width=device-width">
<title>Ghurlbot manual</title>
<link rel=stylesheet type="text/css"
href="https://www.w3.org/Guide/guide2006.css">
<link rel="shortcut icon"
href="https://www.w3.org/Icons/WWW/Literature.gif">
<style>
table {width: 80%; table-layout: fixed; border-collapse: collapse;
margin-left: auto; margin-right: auto; background: #eee}
th, td {border-bottom: 1px solid #999; padding: 0.5em}
td code {color: black; background: none}
:target::before {content: "⇨"; display: inline-block; width: 1.3em;
margin-left: -1.3em; color: red}
</style>
<h1>Ghurlbot manual</h1>
<p>Ghurlbot (<b>G</b>it<b>H</b>ub <b>URL</b> ro<b>bot</b>) is an IRC
bot that looks up GitHub issues, pull requests or discussions,
creates new issues
and action items, or closes them. It typically has the nickname
‘gb’ on IRC, which is what we will use here.</p>
<p>This manual describes how to interact with a running gb on
IRC. A separate manual is included in
the <a href="https://github.com/w3c/GHURLBot" >program source</a>
and describes how to run ghurlbot.</p>
<h2>Command quick reference</h2>
<table>
<thead>
<tr><th>Command</th> <th>Effect</th></tr>
</thead>
<tbody>
<tr>
<td class=command><code>/invite gb</code></td>
<td><a href="#invite">Invite gb to the current
channel</a></td>
</tr>
<tr>
<td class=command><code>gb, bye</code></td>
<td><a href="#invite">Dismiss gb from the current
channel</a></td>
</tr>
<tr>
<td class=command><code>w3c/aria#15<br>
aria#15<br>
#15</code></td>
<td><a href="#info">Look up an issue (which may also be a pull
request, an action or a discussion)</a></td>
</tr>
<tr>
<td class=command><code>@joe</code></td>
<td><a href="#name">Link to a user profile</a></td>
</tr>
<tr>
<td class=command><code>gb, use w3c/scribe2</code></td>
<td><a href="#repo">Specify a repository to use</a></td>
</tr>
<tr>
<td class=command><code>gb, drop w3c/scribe2</code></td>
<td><a href="#remove">Remove a repository from gb's list</a></td>
</tr>
<tr>
<td class=command><code>Issue: Foo is undefined</code></td>
<td><a href="#create-issue">Create a new issue</a></td>
</tr>
<tr>
<td class=command><code>action Eve: send mail<br>
action: Eve to send mail</code></td>
<td><a href="#create-action">Create a new action</a></td>
</tr>
<tr>
<td class=command><code>action Eve: send mail - due in 2 weeks<br>
action Eve: send mail due 3 June</code></td>
<td><a href="#create-action">Create a new action with a due
date</a></td>
</tr>
<tr>
<td class=command><code>action @eve78: send mail</code></td>
<td><a href="#create-action">Create action using a GitHub
account name</a></td>
</tr>
<tr>
<td class=command><code>close #15</code></td>
<td><a href="#close">Close an issue, action, pull request or
discussion</a></td>
</tr>
<tr>
<td class=command><code>reopen aria/#15</code></td>
<td><a href="#reopen">Reopen an issue, action, pull request or
discussion</a></td>
</tr>
<tr>
<td class=command><code>Note #17 This needs work</code></td>
<td><a href="#comment">Add a comment to an issue, action, pull
request or discussion</a></td>
</tr>
<tr>
<td class=command><code>gb, list open issues with label foo</code>
<td><a href="#search">List issues/actions with various criteria</a></td>
</tr>
<tr>
<td class=command><code>gb, next<br>
gb, next list</code>
<td><a href="#search">List more issues/actions</a></td>
</tr>
<tr>
<td class=command><code>gb, set lines to 8</code>
<td><a href="#maxlines">How many full issues to show at a time</a></td>
</tr>
<tr>
<td class=command><code>gb, off<br>
gb, on</code></td>
<td><a href="#suspend">Stop gb from processing issues,
actions, pull requests, discussions & names; or turn it back
on</a></td>
</tr>
<tr>
<td class=command><code>gb, names off<br>
gb, names on</code></td>
<td><a href="#suspend">Stop gb from processing names; or
turn it back on</a></td>
</tr>
<tr>
<td class=command><code>gb, issues off<br>
gb, issues on</code></td>
<td><a href="#suspend">Stop gb from processing issues,
actions, pull requests & discussions; or turn it back
on</a></td>
</tr>
<tr>
<td class=command><code>gb, delay 20</code></td>
<td><a href="#delay">Set the number of lines before gb
looks up the same issue number</a></td>
</tr>
<tr>
<td class=command><code>gb, ignore RRSAgent, Zakim</code></td>
<td><a href="#ignore">Nicks that cannot open or close issues,
actions, pull requests & discussions</a></td>
</tr>
<tr>
<td class=command><code>gb, don't ignore Zakim</code></td>
<td><a href="#ignore">Let Zakim open/close issues, actions,
pull requests & discussions again</a></td>
</tr>
<tr>
<td class=command><code>gb, Eve = eve78<br>
gb, Eve is eve78</code></td>
<td><a href="#aliases">Define aliases for GitHub account names</a></td>
</tr>
<tr>
<td class=command><code>gb, status</code></td>
<td><a href="#status">Get information about the current delay
and repositories, and whether gb is turned off</a></td>
</tr>
<tr>
<td class=command><code>gb, account</code></td>
<td><a href="#account">Get the name of the GitHub account that
gb uses</a></td>
</tr>
<tr>
<td class=command><code>gb, help</code></td>
<td><a href="#help">Provides a link to the manual</a></td>
</tr>
</table>
<p>Commands for gb, as well as names of repositories and names
of people, are case-insensitive. E.g., ‘issue’ can also be written
as ‘ISSUE’ or ‘iSSue’; and ‘use w3c/scribe2’ can also be written
as ‘USE W3C/SCRIBE2’ or ‘Use W3c/Scribe2’.</p>
<h2 id=info>IRC command to link to an issue</h2>
<p>When somebody types something that looks like a repository name
followed by <code>#</code> and an issue number, gb responds
with the full URL of that issue, action item, pull request or
discussion:</p>
<pre class=command><joe> Let's talk about foo/bar#13.
<gb> https://github.com/foo/bar/issues/13 -> #13</pre>
<p>(The <code>-></code> is understood
by <a href="https://w3c.github.io/scribe2/scribedoc.html"
>scribe.perl</a> and causes the URL to be formatted as a link when
scribe.perl generates HTML from the IRC log.)</p>
<p>Gb also tries to look up the issue on GitHub. If it
succeeds, it not only shows a URL, but also a summary, e.g.:</p>
<pre class=command><joe> Next topic: w3c/scribe2#15
<gb> https://github.com/w3c/scribe2/issues/15 -> CLOSED Issue 15 Feature request: syntax for verbatim lines of code (by dbooth-boston)</pre>
<p>Gb fails to look up an issue if it does not have access to
a GitHub account or if the issue is in a private repository,
see <a href="#account" >‘GitHub account’</a>. Gb may also
fail due to network problems. In these cases the URL is unverified
and may be wrong.</p>
<p id=abbreviate>If you have told gb what repositories you are
discussing
(see <a href="#repo">below</a>), you can abbreviate the repository
name, or even omit it:</p>
<pre class=command><joe> Next topic: #15
<gb> https://github.com/w3c/scribe2/issues/15 -> Issue 15 [closed] Feature request: syntax for verbatim lines of code (dbooth-boston)</pre>
<p>If you have told gb to look at more than one repository,
the above will only look in the repository that was added last. To
look up an issue in one of the other repositories, prefix the
number with the name of the repository:</p>
<pre class=command><joe&lgt; Let's talk about aria#13.</pre>
<p>The prefix only needs to be long enough to be unambiguous. So if
there are no other repositories known to gb that start with
an ‘a’, it is enough to say</p>
<pre class=command><joe> a#13</pre>
<p>You can optionally include the repository owner in the prefix:</p>
<pre class=command><joe> w3c/a#13</pre>
<p>Only if none of the repositories that gb knows start with
those letters, gb assumes that the given name represents the
full name of a repository.</p>
<p>In that case you can omit the owner if it is the same as the
repository at the top of gb's list:</p>
<pre class=command><joe> Is scribe2#3 the same issue?
<gb> https://github.com/w3c/scribe2/issues/3 -> Issue 3 [closed] Errors replacing URLs (nigelmegitt)</pre>
<h2 id=url>Look up an issue by its URL</h2>
<p>When gb sees a URL that looks like the URL of an issue, pull
request or discussion on GitHub, it will try to retrieve its
summary from GitHub. E.g.:
<pre class=command><joe> topic: https://github.com/w3c/scribe2/issues/15
<gb> https://github.com/w3c/scribe2/issues/15 -> CLOSED Issue 15 Feature request: syntax for verbatim lines of code (by dbooth-boston)</pre>
<h2 id=name>IRC command to link to a user name</h2>
<p>When somebody types <code>@</code> plus a name, gb responds with
the full URL to that person or team. E.g.:</p>
<pre class=command><joe> That comment came from @aliciag
<gb> https://github.com/aliciag -> @aliciag</pre>
<p>gb only expands a reference that is on in its own, not one
that seems to be attached to something else, such as an email
address (e.g., ‘[email protected]’). If gb does not seem
to recognize a reference, try to put spaces around it.</p>
<h2 id=ignore>Text that gb ignores</h2>
<p>Because gb is often used on channels where RRSAgent is also
active, it assumes lines that look like substitution and insertion
commands for RRSAgent (more
precisely: <a href="https://w3c.github.io/scribe2/scribedoc.html"
>scribe.perl</a>) are indeed that, and are not meant to be
interpreted by gb. E.g., it will not look up issues 14 and 15 when
lines looks like this:</p>
<pre class=command><joe> s/like #14/like #15/
<joe> i/Discuss/topic: #15/</pre>
<p>Also, borrowing
a <a href="https://github.github.com/gfm/#code-spans" >convention
from the MarkDown</a> markup language often used on GitHub, gb
assumes that text enclosed in equal numbers of backquotes is a
code span in some programming language. Thus, gb will not see
‘@context’ as a user name in these lines:</p>
<pre class=command><joe> Use the JSON-LD `@context`
<eva> How do you use ```@context```?</pre>
<h2 id=repo>Specifying the GitHub repository</h2>
<p>To be able to refer to issues, actions, pull requests and
discussions with the
abbreviated syntax, you need to say what repository is being
discussed on this channel:</p>
<pre class=command><joe> gb, discussing https://github.com/xxx/yyy</pre>
<p>Instead of <code>discussing</code>, you can also
use <code>discuss</code>, <code>use</code>, <code>using</code>, <code>take
up</code>, <code>taking up</code>, <code>this will be</code>
or <code>this is</code>.</p>
<p>The prefix ‘https://github.com/’ is assumed, so you can also say:</p>
<pre class=command><joe> gb, discussing xxx/yyy</pre>
<p>You can list mutliple repositories. And if you previously
specified a repository with the same owner, you can also omit the
owner:</p>
<pre class=command><joe> gb, discussing yyy, zzz</pre>
<p>Every time you use the command, gb will add the given
repository to its list. (Or move it to the top of the list, if it
was already in the list.)
<p>You can also use the syntax
of <a href="https://w3c.github.io/scribe2/scribedoc.html#issue-links"
>scribe.perl</a> (version 205):
<pre class=command><joe> repo: xxx/yyy, zzz</pre>
<p>Instead of <code>repo</code>, you can also
use <code>repos</code>, <code>repository</code> or
<code>repositories</code>.
<p>Gb remembers the repositories even when it is
dismissed from a channel. When it is later asked to rejoin, it
continues using the same repositories.</p>
<h2 id=remove>Stop using a repository</h2>
<p>To remove a repository from the list that gb knows:</p>
<pre class=command><joe> gb, drop xxx/yyy</pre>
<p>Instead of <code>drop</code>, you can also
say <code>forget</code>, <code>remove</code>, <code>don't
use</code> or <code>do not use</code>.</p>
<p>You can list multiple repositories. And you can also use the
syntax
of <a href="https://w3c.github.io/scribe2/scribedoc.html#issue-links"
>scribe.perl</a> (version 205):
<pre class=command><joe> repo- xxx/yyy</pre>
<p>To remove all repositories, you can use an
empty <code>repo</code> command:
<pre class=command><joe> repo:</pre>
<h2 id=create-issue>Creating an issue</h2>
<p>You can create new issues by starting a line
with <code>issue:</code>:</p>
<pre class=command><joe> Issue: is the default 1 or 0?</pre>
<p>The
issue will be created in the repository that is at the top of
gb's list. To create an issue in another repository, you
need to move it to the top first.</p>
<h2 id=create-action>Creating an action</h2>
<p>You can create an action item for somebody with the
following three syntaxes:</p>
<pre class=command><joe> action alex: review chapter 1
<joe> action: alex to review chapter 1
<joe> action: alex: review chapter 1</pre>
<p>You can assign an action to several people at once by separating
their names with commas and/or the word ‘and’. E.g.:</p>
<pre class=command><jope> action alex, kylie, coen: review chapter 1
<joe> action: alex, kylie and coen to review chapter 1</pre>
<p>The action will be created in the repository that is at the top of
gb's list.</p>
<p>You can only assign an action to somebody who is associated with
that repository (an owner or a collaborator).</p>
<p>You can optionally prefix the assignee with <code>@</code>:</p>
<pre class=command><joe> action @alex: review chapter 1</pre>
<p>Instead of somebody's GitHub account name, you can use an IRC
nick or an alias, but only if gb knows what the corresponding
GitHub account is. See <a href="#aliases" >‘Mapping names to
GitHub accounts’</a>.</p>
<p>By default, an action gets a due date in one week, but you can
explicitly set a date:</p>
<pre class=command><joe> action alex: review chapter 1 - due 1 June</pre>
<p>Many different ways of describing a date are supported, including
things like ‘in 2 weeks’, ‘tomorrow’ and ‘next Tuesday’.</p>
<h2 id=close>Closing an issue</h2>
<p>You can close an issue, action, pull request or discussion by
starting a line
with <code>close</code>, followed by an issue number or a URL,
e.g.:</p>
<pre class=command><joe> close aria#15
<joe> close #13
<joe> close w3c/aria#17
<joe> close https://github.com/w3c/scribe2/issues/15</pre>
<p>The
issue number can include the full name of the repository or an
abbreviation, see <a href="#info" >‘IRC command to link to an
issue: #’</a>.
<h2 id=reopen>Reopening an issue</h2>
<p>You can reopen an issue, action, pull request or discussion by
starting a line
with <code>reopen</code>, followed by an issue number or a URL,
e.g.:</p>
<pre class=command><joe> reopen #15
<joe> reopen https://github.com/w3c/scribe2/issues/15</pre>
</pre>
<h2 id=action-format>Creating & editing actions without Gb</h2>
<p>If you create or edit an action by hand directly on GitHub, Gb
can still recognize it if you follow the following rules:</p>
<ol>
<li>
<p>An issue must have the label ‘action’ to be
recognized as an action. (It may have additional
labels.)</p></li>
<li>
<p>It must have one or more assignees.</p></li>
<li>
<p>If it has a due date, the due date must start with the word
‘due‘ and a colon (:) and look like either</p>
<pre class=example>due: YYYY-MM-DD</pre>
<p>or</p>
<pre class=example>due: YYYY-MM-DD (comment)</pre>
<p>where YYYY is the year (4 digits), MM is the month
(2 digits), DD is the day (2 digits). E.g., ‘2023-08-30’. The
comment between parentheses is arbitrary text. The word ‘due’
may have both upper- and lowercase letters (‘DUE’, ‘Due’,
‘DuE’, etc.). A due date must be all on one line with nothing
before it except maybe some white space and nothing after it
except possibly white space and/or a period. (If there are
multiple lines with due dates, Gb will use the first
one.)</p></li>
</ol>
<p>For comparison, actions created by Gb itself have three lines in
the body: A line that says that the action was created as a result
of a command on IRC, an empty line, and a line with a due date.
Example:</p>
<pre class=example>Opened by Eve via IRC channel #aria on irc.w3.org
Due: 2023-11-01 (Wednesday 1 November)</pre>
<h2 id=comment>Adding a comment to an issue</h2>
<p>You can add a comment to an existing issue, action, pull request
or discussion, with
commands <code>note</code> and <code>comment</code>, like
this:</p>
<pre class=command><joe> Note #17: Also related to http://example.org
<joe> Comment aria#17: Great comment!
<joe> comment https://github.com/w3c/scribe2/issues/15: Agreed.
<joe> aria#17 note: discussed on 2024-04-25
<joe> aria#17 comment: See also aria#18.</pre>
<p>The colon (:) may be omitted. Gb will
respond with a pointer to the newly created comment on GitHub.</p>
<h2 id=search>List issues or actions</h2>
<p>You can ask for lists of issues or actions:</p>
<pre class=command><joe> list open issues
<joe> list closed actions
<joe> list all actions</pre>
<p>The answer will be something like:</p>
<pre class=command><gb> #20, #15, #14</pre>
<p>Instead of <code>list</code>, you can also
say <code>find</code>, <code>look
up</code>, <code>get</code>, <code>search</code> or <code>search
for</code>.</p>
<p>You can search for <code>issues</code> or <code>actions</code>.
If you omit the word, gb will search for issues. (An action is a
kind of issue, so searching for issues will also return actions,
but not the other way round.) You can search
for <code>open</code>, <code>closed</code> or <code>all</code>
issues. If you omit the word, gb will search for open
issues. Thus the command</p>
<pre class=command>gb, list</pre>
<p>means <code>list open issues</code>.</p>
<p>You can add criteria to restrict the results:</p>
<ul>
<li><code>from myrepo</code> or <code>from repository
myrepo</code> will list issues from ‘myrepo’
instead of the repository that was added last. The name of the
repository may be <a href="#abbreviate">abbreviated</a> exactly
like when referencing issues.</li>
<li><code>with label foo</code> or <code>with labels foo,
bar</code> will limit the results to issues with all of the
given labels.</li>
<li><code>by joe</code> will only return issues that were created
by joe.</li>
<li><code>for joe</code> will return issues assigned to joe.
Instead of a name, you can also say <code>me</code>. And instead
of <code>for me</code>, you can also start with <code>my</code>,
e.g.: <code>list actions for me</code> is the same as <code>list
my actions</code>.</li>
</ul>
<p>You can add one, two, three or four criteria. E.g.:</p>
<pre class=command><joe> gb, list actions for me from rdf-star</pre>
<p>If the result contains more than 99 issues, gb will list
only the 99 highest numbers. To see the next 99, use this:</p>
<pre class=command><joe> gb, next</pre>
<p><code>next list</code> or <code>find next</code>, etc. also works.
<p>If you add <code>verbosely</code>, <code>full</code>, <code>with
descriptions</code> or <code>in full</code> in an appropriate
place in the command, gb will not show the numbers of the issues,
but the full description of each issue.</p>
<p>In this case gb will, by default, list at most 10 issues.
See <a href="#maxlines" >‘Setting the number of full issues to
display’</a> below to change that number.</p>
<h2 id=maxlines>Setting the number of full issues to display</h2>
<p>When asked to list issues or action with full descriptions, gb
will by default display no more than 10 issues. You can change
that number with something like</p>
<pre class=command><joe> set lines to 12
<joe> lines 12
<joe> lines = 12</pre>
<p>The maximum is 99. But note that, because IRC imposes a limit on
the number of lines per second, listing 10 issues already takes
about 23 seconds.</p>
<h2 id=ignore>IRC nicks that should not open or close issues</h2>
<p>Certain IRC bots may print text that looks like an action or an
issue, but isn't really. E.g., RRSAgent repeats all actions at the
end of a meeting. To stop such bots from inadvertently opening or
closing issues and actions, and avoid noise on the channel, you
can add their names to an ignore list:
<pre class=command><joe> gb, ignore RRSAgent</pre>
<p>You can specify multiple names (separated by commas and/or
spaces). Case doesn't matter: ‘rrsagent’ and ‘RRSAgent’ are the
same.
<p>If you made a mistake, you can say:
<pre class=command><joe> gb, don't ignore RRSAgent</pre>
<p>or
<pre class=command><joe> gb, do not ignore RRSAgent</pre>
<p>IRC nicks are only ignored on the current channel. If you need to
ignore the same nicks on other channels, you need to repeat the
command on each of the channels.
<h2 id=aliases>Mapping names to GitHub accounts</h2>
<p>When you create an action for somebody, it is usually the easiest
to use the IRC nick name of that person. But if the IRC nick is
not the same as the GitHub account name of that person, GitHub
will assign the action to nobody.
<p>To help with that, you can define aliases with <code>=</code>
or <code>is</code>, e.g.:
<pre class=command><joe> gb, Eve = eve78
<joe> gb, dayan is dcslobo</pre>
<p>An initial <code>@</code> is optional:
<pre class=command><joe> gb, Eve = @eve78</pre>
<p>The first name is the one you plan to use when creating actions,
the second is the corresponding GitHub account name. In fact, you
can define arbitrary aliases. They don't have to be IRC nicks.
<p>Gb remembers the aliases even when it leaves and later rejoins.
<p>Be careful with nick changes: gb does not try to track nick
changes for aliases. So if
somebody's nick changes, it is up to you to renew the alias.
<h2 id=invite>Inviting and dismissing the bot</h2>
<p>You can invite the bot to a channel and dismiss it:</p>
<pre class=command><joe> /invite gb
<joe> gb, bye</pre>
<h2 id=suspend>Suspending the bot</h2>
<p>You can tell the bot to stop processing issues, actions, pull
request, discussion and names
without dismissing it from the channel; and turn it back on
again:</p>
<pre class=command><joe> gb, off
<joe> gb, on</pre>
<p>You can ask the bot to stop expanding just persons and teams:</p>
<pre class=command><joe> gb, set names to off
<joe> gb, names off
<joe> gb, names = off</pre>
<p>Instead of <code>off</code>, you can also use <code>no</code>
or <code>false</code>. And instead of <code>names</code> you can
also use <code>persons</code> or <code>teams</code>.</p>
<p>To ask it to stop processing just issues, pull requests, discussions and
actions, the command is:</p>
<pre class=command><joe> gb, set issues to off
<joe> gb, issues off
<joe> gb, issues = off</pre>
<p>To turn processing back on, replace <code>off</code>
by <code>on</code>, <code>yes</code> or <code>true</code>.</p>
<p>When you address Gb directly, it will always respond even if
it is turned off otherwise:</p>
<pre class=command><joe> gb, #13 and #14?
<gb> https://github.com/xxx/yyy/issues/13 -> #13
<gb> https://github.com/xxx/yyy/issues/14 -> #14</pre>
<h2 id=delay>Reducing the number of responses from the bot</h2>
<p>To avoid flooding the IRC conversation, the bot will not react to
an issue number or name if it has already looked up the same
reference recently. By default, it waits until 15 lines have been
typed into the IRC channel before expanding the same reference
again, but that can be configured. All of the following set the
delay to 20 lines:</p>
<pre class=command><joe> gb, set delay to 20
<joe> gb, delay 20
<joe> gb, delay = 20</pre>
<p>The delay only stops the bot from reacting to normal messages in
the channel. When you address Gb directly, it will
respond even if it gave the same URL recently.</p>
<h2 id=status>Inquiring about the current status</h2>
<p>You can ask what repository gb is currently using:</p>
<pre class=command><joe> gb, status?
<gb> Delay is 15 lines, issues are on, names are on and I'm using https://github.com/xxx/yyy</pre>
<h2 id=account>GitHub account</h2>
<p>Gb can be started with or without (the access codes for) a
GitHub account. Without an account, it will expand issue numbers
to URLs, but it cannot look up issue summaries and cannot create
any new issues or actions.</p>
<p>To find out what account gb was started with, use this
command:</p>
<pre class=command><joe> gb, who are you?
<gb> I am using GitHub account joe-bot</pre>
<p>Instead of <code>who are you</code>, you can also
say <code>account</code>, <code>user</code> or <code>login</code>.
<p>If gb, despite having access to a GitHub account, still
fails to look up issues or create new ones, it may be that the
repository is private. In that case the owners of the repository
will have to add gb's account to the list of accepted
collaborators.</p>
<p>To be able to create an <em>action</em>, gb additionally
needs to have ‘push’ access to the repository it is adding the
action to. Without push access, it will create an issue
instead. Push access is typically not granted by default. The
owner of the repository will have to explicitly invite the account
that gb is using and give it at least write access to the
repository.
<h2 id=help>Getting help</h2>
<p>The bot also reacts to <code>help</code> with some information
about itself and a link to this manual.</p>
<h2 id=rate-limit>Built-in rate limit</h2>
<p>For security reasons, Gb will write at most 100 times to a
repository per period of 10 minutes. (I.e., 100 issues or actions
created, closed or reopened; merely looking up an issue does not
count.) After 10 minutes, the count is reset. This limit is per
repository, not per IRC channel. If multiple IRC channels use the
same repository, their counts are added together.
<p>In addition, there is a limit on the total number of GitHub
requests on all repositories and all channels. This includes
making changes to issues, but also looking up information about an
issue. This limit is imposed by GitHub and is currently 5000
operations per hour.
<h2 id=source>Source</h2>
<p>Gb is written in Perl.
The <a href="https://github.com/w3c/GHURLBot" >source</a> is on
GitHub.
<hr>
<address>Created by Bert Bos <a href="mailto:[email protected]"
><[email protected]></a> on 12 January 2022. Last updated
$Date: Thu Mar 9 21:42:00 2023 UTC $ by $Author: Bert Bos $</address>