ASFBot Manual

Introduction

Some of the paragraphs on this page assume you have administrative rights to ASFBot, while other features are intended for everyone. Many of these features requires editing of asfbot.cfg (found in infrastructure/trunk/projects/svnbot/) - if you are a part of Infrastructure, please keep yourself acquainted with its format. Any changes to asfbot.cfg should generally be followed by the reconfigure command on IRC. Reloading the configuration will not interrupt any services. For further information about starting/stopping or installing ASFBot, refer to the README in ASFBot's subversion repository.

User levels and rights (karma)

To use a certain administrative or otherwise sensitive feature of ASFBot, a list of user levels, or karma, is kept, to make sure only those with enough merit can execute it. The following karma levels currently apply:

  • Level 1: Can ask the bot for help
  • Level 3: Can send out meeting summary emails
  • Level 6: Can ask ASFBot to join or leave channels
  • Level 10: Can restart, reload, change configuration and grant/remove karma

Karma can be granted temporarilly via the command karma add [user] [level], or it can be added permanently via asfbot.cfg. If permanent, the users preferred nickname as well as cloak or static host name, followed by the karma level to be given, must be added in the [karma] section of asfbot.cfg, as such:

[karma]
  ...
  JohnDoe apache/committer/johndoe 6

Quick-reference, administrators

The following administrative commands are available:

  • help: Lists all available commands. Type help [command] for additional information on usage.
  • reconfigure: Reloads all configurations and plugins. This is commonly used when you have updated asfbot.cfg.
  • restart: Restarts the ASFBot service, disconnecting and reloading the core script. This should be avoided whenever possible.
  • option [key] [value]: Sets an option for the channel you are in. See help option for a list of common options and values.
  • join [channel name]: Joins a new channel with a bare configuration for it.
    If you have added a new channel to asfbot.cfg, you may need run this command followed by reconfigure to set it up properly.
  • leave: Leaves the current channel.

Quick-reference, regular users

The following commands are available for all to use:

  • tell [target] [message]: Sends a message to [target] when he/she either logs back onto the channel or starts to speak again (details).
  • issue #[issueno]: Searches the Bugzilla database for that specific bug and displays relevant information (details).
  • jira [issueno]: Displays a link to the relevant JIRA issue if the channel is configured for this (details).
  • r[revision no.]: Displays information about a specific subversion revision (details).
  • meeting [start|end]: Starts or ends recording an IRC meeting for later publication (details).

Subversion, Git and JIRA reporting

ASFBot can report on new commits to your Subversion or Git repository - similar to the old CIA services - or report when a JIRA ticket was created, updated, closed etc. These reports can be tailored to your individual needs; multiline logs, compacted paragraphs, coloring, different report styles etc.

You can subscribe to any repository you like, and get reports on any specific changes you prefer, as long as these changes are publicly available.

Subscriptions are tag-based, meaning that any one tag will apply to f.x. both Subversion and git commits.

To set up git or subversion reporting, asfbot.cfg must be edited, adding the appropriate channel to the list and subscribing to tags, as such:

[Channel:#testchannel]
  tags: test dist/test
  ....

After this is done, and the configuration is updated on the host machine, you should issue a reconfigure command to reload the settings. Regular users should refer to infra to handle this task.

For JIRA tickets, the appropriate tag to add is JIRA:[JIRA project name]. the address asfbot@urd.zones.apache.org must be set up as a recipient of emails pertaining to changes to your JIRA tickets for it to take effect. If you are a moderator of the dev@ list of your project, you can send an email to: dev-allow-subscribe-asfbot=urd.zones.apache.org@[project].apache.org to hand JIRA updates to ASFBot's inbox. If not, please contact infra.

Jenkins integration

ASFBot can report on build failues/successes on the ASF Jenkins instance via the Jenkins RSS feed.

To set up Jenkins reporting, asfbot.cfg must be edited, adding the appropriate channel to the list and subscribing to tags, as such:

[Channel:#testchannel]
  jenkins_rss:   https://builds.apache.org/rssLatest
  jenkins_match: foo_project
  ....

The jenkins_rss field should always be as written above, unless you are using an external Jenkins instance. The jenkins_match field should match (part of) the name of the build job on Jenkins.

After this is done, and the configuration is updated on the host machine, you should issue a reconfigure command to reload the settings. Regular users should refer to infra to handle this task.

JIRA search

If your channel is set up for JIRA search, you can find tickets matching a specific keyword by using the search command. To search for issued related to, for instance, 'libvirtd' type: ASFBot: search libvirtd:

<Humbedooh>: ASFBot: search libvirtd
<ASFBot>: https://issues.apache.org/jira/browse/CLOUDSTACK-4631 - [Automation] Failed to create snapshot from volume due to storage pool missing error in libvirtd

Latest JIRA change

If your channel is set up for JIRA reporting, ASFBot will keep track of the latest changes to a JIRA ticket. To view, for instance, the last comment pertaining to an issue, simply type: ASFBot: comment [ticket] where ticket could be fx. INFRA-1234.

Issue information fetching

ASFBot can assist people in finding the correct information or link regarding specific JIRA or Bugzilla issues. To use this feature, simply type f.x. "issue #52230" to get a link for the Bugzilla issue no. 52230 and a quick summary of the issue, as shown here:

<Humbedooh>: issue #52247
<ASFBot>: Humbedooh: https://issues.apache.org/bugzilla/show_bug.cgi?id=52247 - mod_mbox gives up on unexpected message format

You could also type COUCHDB-1234 or simply jira 1234 to get a link to that specific JIRA ticket:

<Humbedooh>: jira 1629
<ASFBot> Humbedooh: » https://issues.apache.org/jira/browse/COUCHDB-1629 - CouchDB is not fully cleaning up deleted view folders

For Subversion, it is also possible to fetch information about a specific revision, by typing, for example: r123456 on a line, for instance:

<Humbedooh>: r424680
<ASFBot> Humbedooh: » r424680 | jerenkrantz | 2006-07-23 05:55:58 +0000 (Sun, 23 Jul 2006) | 3 lines
<ASFBot> Humbedooh: » Add -m option to mod-mbox-util to dump the mbox message-id cache
<ASFBot> Humbedooh: » (replaces the load_msgid tool which was never updated when this was introduced.)

Commenting and replying via IRC

It is possible to comment on either JIRA tickets or reply to a comment in the comments.apache.org system using ASFBot.

To comment on a JIRA ticket, use the comment [ticket id] [message] syntax, as such:

<Humbedooh> ASFBot: comment CLOUDSTACK-1234 This is a reply to something on the CLOUDSTACK-1234 ticket in JIRA.
<ASFBot> Commented on CLOUDSTACK-1234

To reply to a comment on the comments system, use the following syntax: reply [post id] [message], for example:

<Humbedooh> ASFBot: reply 1234 This is a reply to a comment.
<ASFBot> Replied to post 1234 on the httpd site.

In both cases, the replies will be written by the user ASFBot, but will include your IRC nickname in the message. JIRA commenting requires level 3 karma, while replying to comments on the comments.a.o system requires asfbot.cfg to be set up with a specific karma list for the channel, as such:

[Channel:#testchannel]
  karma:    fooUser barUser testUser
  ....

Secretary feature

ASFBot provides a simple secretary feature for all to use. To leave a message for an absent person, simply write: ASFBot: tell [recipient] [message], and that message will be passed on the next time that person logs onto the channel.

Record keeping for meetings

ASFBot can keep a record of meetings done on IRC and publish these in HTML format with an agenda, actions to be taken and members present.

Record keeping is only allowed in channels where logging is enabled. Logging is enabled by setting the allowLogging variable to true in the appropriate channel section in asfbot.cfg, for instance:

[Channel:#testchannel]
  allowLogging: true
  tags: test JIRA:test
  ....
For regular users, please contact the infrastructure team, either via a JIRA ticket or on #asfinfra, and have them do this..

How to record a meeting

Record keeping works as follows:

  • To initiate a meeting, type ASFBot: meeting start.
  • To set an agenda, either type #topic [agenda goes here] or use the /topic command to change the channel's topic.
    ASFBot will keep the original topic of the channel in memory, and change it back once the meeting is over.
    For this feature to work properly, your channel must not have mode +t set.
  • To add an information to the meeting summary, type #info [something here].
  • To add an action to be taken before the next meeting, type #action [action].
  • To add a link to the meeting summary, type #link [url].
  • To end a meeting and save a summary of it, type ASFBot: meeting end.
    This will end the record keeping and produce an HTML document containing the summary of the meeting as well as a log of everything that was said.
  • To send an IRC meeting summary as an email to a recipient, type ASFBot: meeting send your@domain.tld.
    You will need to have been granted at least karma level 3 by infrastructure to perform this task, and the meeting will need to have ended before you can send out a summary email.

Anything said with [off] at the beginning will be considered off-the-record and will not be written in the meeting log, as for instance in this dialogue:

<JohnDoe>: This is on record
<JohnDoe>: [off] This is off record
<JaneDoe>: This is on record again

In most regards, ASFBot will understand the meetbot commands, and as such, #meetingstart or #meetingend will also start or end a recording of a meeting.

Once a meeting has ended, a HTML version of it will be archived in the public archives.

For an example of what a meeting summary may look like, check out this CouchDB meeting

Integration with comments.apache.org

ASFBot can relay comments provided via comments.apache.org to your IRC channel. If you have set up a karma list with Infrastructure, you can also reply to comments via IRC.

To set up a channel for comments reporting, edit asfbot.cfg and add comments:[comments site id] to the list of tags to monitor. Furthermore, if IRC users should be allowed to respond to comments via IRC, a karma list must be added, containing the names of those who are allowed to reply to comments:

[Channel:#testchannel]
  tags: comments:test
  karma: JohnDoe JaneDoe

After this is done, issue a reconfigure command to ASFBot and comments should be integrated with the channel.

Comments