==================================================== MeetBot, a supybot plugin for IRC meeting notetaking ==================================================== Introduction ============ MeetBot is a plugin to the IRC bot supybot to facilitate taking of notes during IRC meetings. This allows you to better communicate with your project or groups after the IRC meeting, as well as keep the meeting more under control and on-topic. This manual is for user and meeting chair reference. For installation support, see ``README.txt``. Tutorial ======== Let's go through, step by step, how a typical meeting might run:: < MrBeige> #startmeeting We use the ``#startmeeting`` command to tell MeetBot to start the meeting. The person who calls the command becomes the chair - having the power to guide the meeting. However, by default MeetBot allows other participants to enter most things into the logs, since inviting contributions is generally a good thing.:: < MeetBot> Meeting started Wed Jun 17 05:00:49 2009 UTC. The chair is MrBeige. < MeetBot> Information about MeetBot at http://wiki.debian.org/MeetBot , Useful Commands: #action #agreed #halp #info #idea #link #topic. MeetBot gives us a little bit of information about the meeting.:: < MrBeige> #topic should we release or not? -!- MeetBot changed the topic of #meetbot-test to: should we release or not? We use the ``#topic`` command to tell MeetBot to move to the first topic. MeetBot sets the topic in the channel to the topic which is given on the line. Don't worry, the topic will be restored at the end of the meeting.:: < MrBeige> #info we have two major blocking bugs: the character set conversion, and the segfaults heisenbug in the save routine. When there is important things said, we don't want them to be lost in the irclogs. Thus, we use the ``#info`` command to make a note of it in the meeting minutes. It is also highlighted in the irclogs which MeetBot takes.:: < MrBeige> #agreed we give one week to fix these (no other changes accepted), and then release We also have the ``#agreed`` command to use. This can only be used by the chairs of the meeting, and should (obviously) be used to document agreement. The rest of the line goes into the minutes as the thing agreed on.:: < MrBeige> #action MrGreen and MrMauve work together to fix the bugs < MrBeige> #action MrBeige releases when done We have the ``#action`` command. This one is works just like the last two, but has one extra feature: at the end of the meeting, it makes a list of "Action Items", useful for being sure things get taken care of. But there is more: it also makes a list of action items sorted by *nick*. This can be used to easily see what is assigned to you. In order for an item to be sorted by a nick, that nick has got to say something during the meeting (but also see the ``#nick`` command), and you have to use their nick exactly (use tab completion!).:: < MrBeige> #topic goals for release after next -!- MeetBot changed the topic of #meetbot-test to: goals for release after next Moving on to the next topic...:: ... < MrBeige> #info make it better ... < MrBeige> #info release faster ... Record some of the important items from this section.:: < MrBeige> #endmeeting Hit the ``#endmeeting`` command. The meeting ends, and logs and minutes are saved:: -!- MeetBot changed the topic of #meetbot-test to: General discussion of MeetBot < MeetBot> Meeting ended Wed Jun 17 05:03:45 2009 UTC. Information about MeetBot at http://wiki.debian.org/MeetBot . < MeetBot> Minutes: http://rkd.zgib.net/meetbot/meetbot-test/meetbot-test.html < MeetBot> Log: http://rkd.zgib.net/meetbot/meetbot-test/meetbot-test.log.html MeetBot conveniently tells us where all of the logs are stored. You can look at the `logs`_ and `minutes`_ online. .. _logs: http://rkd .. _minutes: http://rkd Commands ======== All commands are case-insensitive, and use the ``#`` prefix character. Not all commands have output. This might be confusing, because you don't know if it's been acted on or not. However, this is a conscious design decision to try to keep out of the way and not distract from the real people. If something goes wrong, you can adjust and have MeetBot re-process the logs later. #startmeeting Starts a meeting. The calling nick becomes the chair. If any text is given on the rest of the line, this becomes the meeting topic, see ``#meetingtopic`` above. #endmeeting End a meeting, save logs, restore previous topic, give links to logs. You know the drill. (Chairs only.) #topic Set the current topic of discussion. MeetBot changes the topic in the channel (saving the original topic to be restored at the end of the meeting). (Chairs only.) #agreed (alias #agree) Mark something as agreed on. The rest of the line is the details. (Chairs only.) #chair and #unchair Add new chairs to the meeting. The rest of the line is a list of nicks, separated by commas and/or spaces. The nick which started the meeting is the ``owner`` and can't be de-chaired. The command replies with a list of the current chairs, for verification (Chairs only.) Example:: < MrBeige> #chair MrGreen MsAlizarin < MeetBot> Current chairs are: MsAlizarin MrBeige MrGreen #action Add an ``ACTION`` item to the minutes. Provide irc nicks of people involved, and will be both a complete listing of action items, and a listing of action items sorted by nick at the end of the meeting. This is very useful for making sure this gets done. Example:: < MrBeige> #action MrGreen will read the entire Internet to determine why the hive cluster is under attack. If MrGreen has said something during the meeting, this will be automatically assigned to him. #info Add an ``INFO`` item to the minutes. Example:: < MrBeige> #info We need to spawn more overlords before the next release. #link Add a link to the minutes. The URL must be the first thing on the line, separated by a space from the rest of the line, and it will be properly hyperlinked. This command is automatically detected if the line starts with http:, https:, mailto:, and some other common protocols defined in the ``UrlProtocols`` configuration variable. Examples:: < MrBeige> #link http://wiki.debian.org/MeetBot/ is the main page < MrBeige> http://wiki.debian.org/MeetBot/ is the main page Both of these two examples are equivalent, and will hyperlink properly. The first example below won't hyperlink properly, the second one won't be automatically detected:: < MrBeige> #link the main page is http://wiki.debian.org/MeetBot/ < MrBeige> the main page is http://wiki.debian.org/MeetBot/ Less-used Commands ================== #meetingtopic Sets the "meeting topic". This will always appear in the topic in the channel, even as the #topic changes. The format of the IRCtopic is " (Meeting Topic: )". (Chairs only.) #commands List recognized supybot commands. This is the actual "help" command. #idea Add an ``IDEA`` to the minutes. #help (alias #halp) Add a ``HELP`` item to the minutes. Confusingly, this does *not* give supybot help. See #commands. #accepted (alias #accept) Mark something as accepted. The rest of the line is the details. (Chairs only.) #rejected (alias #reject) Mark something as rejected. The rest of the line is the details. (Chairs only.) #save Write out the logs right now. (Chairs only.) #nick Make a nick be recognized by supybot, even though it hasn't said anything. This is only useful in order to make a list of action items be grouped by this nick at the end of the meeting. #undo Remove the last item from the meeting minutes. Only applies to commands which appear in the final output. #restrictlogs When logs are saved, remove the permissions specified in the configuration variable ``RestrictPerm``. (Chairs only.) #lurk and #unlurk When ``lurk`` is set, MeetBot will only passively listen and take notes (and save the notes), not reply or change the topic This is useful for when you don't want disruptions during the meeting. (Chairs only.) #meetingname Provide a friendly name which can be used as a variable in the filename patterns. For example, you can set filenamePattern = '%(channel)s/%%Y/%(meetingname)s.%%F-%%H.%%M' to allow #meetingname to categorize multiple types of meeting occurring in one channel. All spaces are removed from the rest of the line and the string is converted to lowercase. If ``meetingname`` is not provided, it defaults to ``channel``. (Chairs only.) Supybot Admin Commands ====================== These commands are for the bot owners to manage all meetings served by their bot. The expected use of these commands is when the bot is on many channels as a public service, and the bot owner sometimes needs to be able to monitor and adjust the overall situation, even if she is not the chair of a meeting. All of these are regular supybot commands (as opposed to the commands above). That means that the supybot capability system applies, and they can be given either in any channel, either by direct address (``BotName: ...``) or with the bot prefix character (e.g. ``@ ...``). These are restricted to anyone with the ``admin`` capability on the bot. ``listmeetings`` List all meetings. ``savemeetings`` Saves all active meetings on all channels and all networks. ``addchair `` Forcibly adds this nick as a chair on the giver channel on the given network, if a meeting is active there. ``deletemeeting `` Delete a meeting from the cache. If save is given, save the meeting first. The default value of ``save`` is True. This is useful for when MeetBot becomes broken and is unable to properly save a meeting, rendering the ``#endmeeting`` command non-functional. Hints on how to run an effective meeting ======================================== *Please contribute to this section!* * Have an agenda. Think about the agenda beforehand, so that attendees are not tempted to jump ahead and discuss future items. This will make it very hard to follow. * *Liberally* use the ``#action`` command, making sure to include the nick of the person responsible. It will produce an easy-to-scan list of things to do, as well as a sorted-by-nick version. This will make these things more likely to get done. * In the same spirit, liberally use ``#info`` on important pieces of data. If you think you'll want to refer to it again, ``#info`` it. Assigning someone to watch the meeting to ``#info`` other people's lines (if they forget) usually pays off. * Don't be afraid to tell attendees to wait for a future topic to discuss something. * Delegate where possible and have those interested discuss the details after the meeting, where applicable. No need to take everyone's time if not everyone needs to decide. (This only applies to some types of meetings) * Sometimes one chair to manage the topic at hand, and one chair to manage all people who are going off-topic, can help. Configuration ============= Configuration is done by creating a file ``meetingLocalConfig.py`` in the plugin directory, or somewhere in your PYTHONPATH. It works by (automatically, not user-visible) subclassing the Config class. Here is a minimal usage example. You need at *least* this much to make it run. Put this in ``meetingLocalConfig.py`` before you first start supybot:: Class Config(object): # These two are **required**: logFileDir = '/home/richard/meetbot/' logUrlPrefix = 'http://rkd.zgib.net/meetbot/' Two other more commonly used options are:: filenamePattern = '%(channel)s/%%Y/%(channel)s.%%F-%%H.%%M' MeetBotInfoURL = 'http://some_other_side.tld' Place all of the configuration variables inside of the class body like this. ``meetingLocalConfig.py`` is a complete execution, and causes a subclass of the main Config object. Thus, you can do some advanced (or just crazy) things like add a new meeting command, meeting agenda item type, or more. Not all of these are documented here. To reload a configuration in a running supybot, you can just reload the plugin in supybot --- the module is reloaded. Specifically, ``/msg YourBotName reload MeetBot``. Supybot-based Config -------------------- In addition to the normal ``meetingLocalConfig.py`` based configuration, there is a mode where the supybot registry system can be used to set the values of some configuration variables. To enable this system, first the ``supybot.plugins.MeetBot.enableSupybotBasedConfig`` variable must be set to True. Then the MeetBot plugin must be reloaded:: /msg YourBot config supybot.plugins.MeetBot.enableSupybotBasedConfig True /msg YourBot reload MeetBot Now you can list the values available for configuration (the list below may not be up to date):: /msg YourBot config list supybot.plugins.MeetBot ----> #endMeetingMessage, #filenamePattern, #input_codec, #logFileDir, #logUrlPrefix, #MeetBotInfoURL, #output_codec, #pygmentizeStyle, #specialChannelFilenamePattern, #startMeetingMessage, #timeZone, #usefulCommands, enableSupybotBasedConfig, and public Setting a value for a variable:: /msg YourBot config supybot.plugins.MeetBot.logUrlPrefix ... ... http://meetings.yoursite.net/ At present, not all variables are exported to supybot. All string variables are, as well certain other variables for which a wrapper has been written. If a variable doesn't appear in the supybot registry, it can't be set via the registry. If you want to disable supybot-based config for security reasons, set ``dontBotConfig`` to True in your custom configuration class in ``meetingLocalConfig.py``. Required or Important Configuration ----------------------------------- These variables are set either in ``meetingLocalConfig.py`` (in the ``Config`` class) or in the supybot registry. ``logFileDir`` The filesystem directory in which the meeting outputs are stored. **Required** or supybot can't save properly. ``logUrlPrefix`` The URL corresponding to ``logFileDir``. This is prepended to filenames when giving end-of-meeting links in the channel. **Required** or supybot's URLs will be wrong. ``filenamePattern`` This defaults to ``'%(channel)s/%%Y/%(channel)s.%%F-%%H.%%M'``, and is the pattern used for replacements to identify the name of the file basename (including possible sub-directories) in which to store the meeting output files. This is the suffix to ``logFileDir`` and ``logUrlPrefix``. Variables available for replacement using ``%(name)s`` include: ``channel``, ``meetingname``. Double percent signs (e.g.: ``%%Y`` are time formats, from ``time.strftime``. This filename does *not* include extensions. Those are found from the writers, via the variable ``writer_map``. Putting these all together, a set of variables could be: 1) ``logFileDir = /srv/www/meetings/`` 2) ``%(channel)s/%%Y/%(channel)s.%%F-%%H.%%M`` 3) (extensions come from ``writers_map``) ``MeetBotInfoURL`` This is a URL given in beginning and ending messages and minutes files as a "go here for more information" link. Other Config Variables ---------------------- These variables are set either in ``meetingLocalConfig.py`` (in the ``Config`` class) or in the supybot registry. ``RestrictPerm`` An int listing which permissions to remove when using the ``#restrictlogs`` command. It is best to use the python ``stat`` module to set it:: RestrictPerm = stat.S_IRWXO|stat.S_IRWXG ``specialChannels`` and ``specialChannelFilenamePattern`` When you are doing MeetBot testing, you would rather not have nonstop different filenames each time you do a test meeting. If a channel is in ``specialChannels``, it will use ``specialChannelFilenamePattern`` instead of ``filenamePattern`` when storing logs. ``specialChannels`` is a tuple listing channel names. Example: the defaults are ``("#meetbot-test", "#meetbot-test2")`` and ``'%(channel)s/%(channel)s'`` (note that there is no time-dependence in the name). ``UrlProtocols`` Tuple of protocols to use to automatically detect link. Example: the default tuple is ``('http:', 'https:', 'irc:', 'ftp:', 'mailto:', 'ssh:')``. ``command_RE`` How commands are detected. See code. ``pygmentizeStyle`` Style for the Pygments module to use to colorize the IRC logs. The default is ``"friendly"``. ``timeZone`` Timezone used in the bot. Note: This will not yet work on a per-channel basis. The default is ``"UTC"`` ``startMeetingMessage`` ``endMeetingMessage`` Message printed at the beginning/end of the meetings. Some ``%(name)s`` replacements are available: ``chair``, ``starttime``, ``timeZone``, ``endtime``, ``MeetBotInfoURL``, ``urlBasename``. ``input_codec`` ``output_codec`` Input and output character set encodings. ``writer_map`` A python dictionary listing what output formats will be used to write our final results to a file, along with extensions to use. For example:: writer_map = { '.log.html':writers.HTMLlog(), '.html': writers.HTML(), '.txt': writers.RST(), #'.rst.html':writers.HTMLfromRST(), } Advanced Configuration ---------------------- This gives a few examples of things you can do via ``meetingLocalConfig.py``. Most people probably won't need these things, and they aren't thoroughly explained here. You can make a per-channel config:: class Config(object): def init(self): if self.M.channel == '#some-channel': self.logFileDir = '/some/directory' else: self.logFileDir = '/some/other/directory' The display styles (in html writers) can be modified also, by using the starthtml and endhtml attributes (put this in meetingLocalConfig.py:: import items items.Agreed.starthtml = '' items.Agreed.endhtml = '' Adding a new custom command via ``meetingLocalConfig.py``. This likely won't make sense unless you examine the code a bit:: class Config(object): def init(self): def do_party(self, nick, time_, **kwargs): self.reply("We're having a party in this code!") self.reply(("Owner, Chairs: %s %s"%( self.owner,sorted(self.chairs.keys())))) self.M.do_party = types.MethodType( do_party, self.M, self.M.__class__) Make a command alias. Make ``#weagree`` an alias for ``#agreed``:: class Config(object): def init(self): self.M.do_weagree = self.M.do_agreed Help and Support ================ The channel ``#meetbot`` on irc.oftc.net is the best place to go.