#####################################
ASFBot - Multipurpose secretarial bot
#####################################


========================
Installation and running
========================
1) Download the bot from https://svn.apache.org/repos/infra/infrastructure/trunk/projects/asfbot/
2) Install Python 3.x (no longer works with Python 2)
3) Set up default channels and options in asfbot.cfg (use your favorite text editor)
4) run: python asfbot.py foreground (This should be done from ASFBot's folder, eg /usr/local/etc/asfbot)
### tbd: instructions on using systemd to daemonize this service

=============
Local testing
=============
1) install irc (python3 -mpip install irc)
2) Change to ASFBot home directory
3) copy asfbot.cfg.example to asfbot.cfg
4) start irc server:  python3 test/testserver.py -l DEBUG
5) (in another shell session) run: python3 asfbot.py foreground

=====
Karma
=====
Karma is used to access the features that are not meant for everyone.
Infrastructure people will usually have a karma level of 10, which grants access to all features.
To give a specific person karma on IRC, use the following command:
`ASFBot: karma add [nick] [level]`, for example: `ASFBot: karma add Humbedooh 3`.
This karma will be tied to the ident of the user, so please try to constrain this to registered users 
with a working cloak. To make the karma stick, add an entry in asfbot.cfg in the [Karma] section, as such:

  johndoe    apache/committer/johndoe 3
  
The following karma levels are in effect (more to be added):

[Action]                            [Required karma]
Restart/stop ASFBot                     10
Reload configuration                    10
Set an option                           10
Grant/remove karma                      10
Display PubSub status                    8
Reconnect to a PubSub service            8
Send an alert/speak as ASFBot (wall)     8
Join/leave a channel                     8
Subscribe/unsubscribe to repos           6
List channel subscriptions               3
Use the meeting recording feature        3
Send emails with meeting summaries       3
Use the 'help' feature                   0
Use the 'tell' feature                   0
Use the issue info feature               0
Use the beer tab                         0

====================
Setting up reporting
====================
Reporting should initially be set up via the IRC interface, by asking ASFBot to join the appropriate channel.
The following commands are usually used via #asftest:

1) `ASFBot: join #channel-name`
   (Join the channel yourself and execute step 2 in there)
2) `ASFBot: subscribe projectname`

Once that is done, add an entry to the `channels` list in asfbot.cfg and commit the changes:

[channel:#channel-name]
  tags: project-subversion-name othertag thirdtag

You can use `ASFBot: reload` to reload asfbot.cfg with your changes (don't forget to svn up first!)

For incubator projects, use the special tag `incubator.projectname` which will match against both 
`incubator/projectname` (Subversion) and `incubator-projectname` (Git repository).

============
IRC Meetings
============
If the email feature is to be used, each person chairing a meeting should be set up with karma 
level 3 in the main [karma] configuration, fx:

  johndoe apache/committer/johndoe 3

============
IRC Commands
============
IRC Commands can be used by IRC users with karma (see asfbot.cfg for the default list of users)

wall [message]                     : Sends a message to all IRC channels ASFBot is in
help                                : Lists the available commands

join [channel name]                 : Joins a channel
leave                               : Leaves the channel from which the command was issued

subscribe [pattern]                 : Subscribes the current channel to directories matching [pattern] (using Lua Patterns)
unsubscribe [pattern]               : Unsubscribes the current channel from directories matching [pattern] (using Lua Patterns)
subs                                : Lists the currently subscribed directories for the current channel

karma [add|remove|list] [user]      : Adds/removes/list karma (add people to config.lua for permanent karma)

option [value] [key]                : Sets an option specific to the channel. Use `help option` for more information
reload                              : Reloads the configuration and any plugins available in the scripts folder
reply [comment id] [message]        : Replies to a comment through comments.apache.org
comment [jira ticket id] [message]  : Replies to a comment through JIRA
restart                             : Restarts the IRC service. This is mainly used for reloading the core features
status                              : Displays the current svnpubsub connection status
tell [recipient] [message]          : Notifies [recipient] of a message when he/she joins the channel or starts to talk.
meeting [start|end]                 : Start/stop recording a meeting in a channel.



#####################################

PROTOCOL

Interesting notes:
http://books.gigatux.nl/mirror/irchacks/059600687X/irchks-CHP-13-SECT-2.html