Source code for the PTG event scheduling bot
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.rst 7.6KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254
  1. ===========================
  2. Open Infrastructure PTG Bot
  3. ===========================
  4. ptgbot is the bot that PTG track moderators use to surface what's
  5. currently happening at the event. Track moderators send messages to
  6. the bot, and from that information the bot builds a static webpage
  7. with several sections of information:
  8. * The discussion topics currently discussed ("now")
  9. * An indicative set of discussion topics coming up next ("next")
  10. * The tracks pre-scheduled for the day
  11. * The tracks which booked available slots in the additional rooms
  12. The bot also allows people to voluntarily check into (and out of)
  13. tracks or other arbitrary locations, if they want to be found more
  14. easily by other people.
  15. User commands
  16. =============
  17. Anyone can privately message the bot with the following commands:
  18. * ``in #TRACKNAME`` - tells the bot you are currently in the track
  19. named ``TRACKNAME``. This must be one of the tracks it knows about,
  20. for example: ``in #nova``
  21. * ``in LOCATION`` - tells the bot you are currently in a location
  22. which doesn't correspond to any track. This can be any freeform
  23. text, for example: ``in the pub``
  24. * ``out`` - tells the bot you've checked out of your current location.
  25. However others will still be able to see when and where you checked
  26. out.
  27. * ``seen NICK`` - asks the bot where the user with the given IRC nick
  28. was last seen (if anywhere). The nick is case-insensitive.
  29. * ``subscribe REGEXP`` - subscribes for a direct message notification
  30. from the bot whenever a topic with a substring matching ``REGEXP``
  31. is set via the ``now`` or ``next`` commands (see below). The exact
  32. string the (case-insensitive) regular expression will be matched
  33. against is of the form ``#track now topic`` (i.e. the same as the
  34. full commands issued by track moderators). So for example
  35. ``subscribe #nova.*test|python *3`` would match any testing topics
  36. in the nova track, and any Python 3 topics in any track.
  37. * ``subscribe`` - shows your current subscription regular expression
  38. (if any)
  39. * ``unsubscribe`` - cancels your current subscription (if any)
  40. The above commands also work in the channel when prefixed with ``#``,
  41. for example ``#in the pub``. You can use the ``#`` prefix with
  42. private messages to the bot too, in case you don't want to memorise
  43. different syntax for these commands depending on whether you are
  44. messaging the bot privately or in a channel.
  45. Track moderators commands
  46. =========================
  47. By default the bot allows anyone in the channel to issue track moderation
  48. commands. However note that it is possible for admins to restrict access
  49. to people who have voice in the channel (+v).
  50. Commands follow the following format::
  51. #TRACKNAME COMMAND [PARAMETERS]
  52. Here is the list of available commands.
  53. now
  54. ---
  55. The ``now`` command indicates the current topic of discussion in a given
  56. track. Example usage::
  57. #swift now discussing ring placement
  58. * Your track needs to exist in the system, and be scheduled in the day.
  59. Information about the room will be added automatically from the schedule.
  60. * You can mention other tracks by using the corresponding hashtags, like:
  61. ``#nova now discussing multi-attach with #cinder``.
  62. * There can only be one ``now`` discussion topic at a time. If multiple
  63. topics are discussed at the same time in various corners of the room,
  64. they should all be specified in a single ``now`` command.
  65. * In order to ensure that information is current, entering a ``now`` command
  66. wipes out any ``next`` entry for the same track.
  67. next
  68. ----
  69. The ``next`` command lets you communicate the upcoming topics of discussion in
  70. your track. You can use it as a teaser for things to come. Example usage::
  71. #swift next at 2pm we plan to discuss #glance support
  72. #swift next around 3pm we plan to cover cold storage features
  73. * Your track needs to exist in the system, and be scheduled in the day.
  74. * You can specify multiple ``next`` discussion topics. To clear the list, you
  75. can enter a new ``now`` discussion topic, or use the ``clean`` command.
  76. * Since passing a new ``now`` command wipes out the ``next`` entries, you
  77. might want to refresh those after entering a ``now`` topic.
  78. book
  79. ----
  80. The ``book`` command is used to book available slots in the additional rooms.
  81. Available time slots (at the bottom of the PTGbot page) display a slot code
  82. you can use book the room. Example usage::
  83. #vitrage book Missouri-MonAM
  84. * Your track needs to exist in the system.
  85. * Once you booked the slot, you are part of the schedule for the day, and
  86. you can use the ``now`` and ``next`` commands to communicate what topic
  87. is being discussed.
  88. unbook
  89. ------
  90. The ``unbook`` command is used to free up booked slots in the additional rooms.
  91. You should generally not unbook a track without the consent of its track lead.
  92. Example usage::
  93. #vitrage unbook Missouri-MonAM
  94. clean
  95. -----
  96. You can remove all ``now`` and ``next`` entries related to your track by
  97. issuing the ``clean`` command (with no argument). Example usage::
  98. #ironic clean
  99. etherpad
  100. --------
  101. By default the bot generates etherpad links for all tracks. If you already
  102. have an etherpad, you can set its URL using the ``etherpad`` command::
  103. #keystone etherpad https://etherpad.openstack.org/p/awesome-keystone-pad
  104. If you set a URL and would like to revert to the autogenerated name, you can
  105. pass ``auto`` as the etherpad URL::
  106. #keystone etherpad auto
  107. color
  108. -----
  109. By default all tracks appear as blue badges on the page. You can set your
  110. own color using the ``color`` command. Colors can be specified in any
  111. form supported by the CSS attribute background-color::
  112. #infra color red
  113. #oslo color #42f4c5
  114. * The color command only sets the background color for the track
  115. name. The foreground is always white.
  116. location
  117. --------
  118. The room your track discussions happen in should be filled automatically
  119. by the PTGbot by looking up the schedule information. In case it's not right,
  120. you can overwrite it using the ``location`` command. Example usage::
  121. #oslo location Level B, Ballroom A
  122. Admin commands
  123. ==============
  124. You have to be a channel operator (+o) to use admin commands.
  125. ~list
  126. List available track names
  127. ~add TRACK [TRACK..]
  128. Add new track(s)
  129. ~del TRACK [TRACK..]
  130. Deletes track(s)
  131. ~clean TRACK [TRACK..]
  132. Removes active entries for specified track(s)
  133. ~newday
  134. Removes existing now/next/location/presence entries. This command is
  135. meant to be run at the start of a new day
  136. ~motd LEVEL MESSAGE
  137. Adds a message of the day on top of the rendered page. Level must be one of
  138. info, success, warning or danger.
  139. ~cleanmotd
  140. Removes message of the day on top of the rendered page.
  141. ~emptydb
  142. Resets the database entirely to minimal contents
  143. ~fetchdb URL
  144. Fetches JSON DB from specified URL. Any JSON key specified will replace
  145. existing data in database.
  146. ~requirevoice
  147. Requires that users are voiced (+v) to issue track moderation commands
  148. ~alloweveryone
  149. Allows everyone in the channel to issue track moderation commands
  150. Local testing
  151. =============
  152. Copy config.json.sample to config.json::
  153. cp config.json.sample config.json
  154. Edit config.json contents, for example::
  155. {
  156. "irc_nick": "ptgbot",
  157. "irc_server": "irc.freenode.net",
  158. "irc_port": 6697,
  159. "irc_channel": "#testptg",
  160. "db_filename": "html/ptg.json",
  161. }
  162. In one terminal, run the bot::
  163. tox -evenv -- ptgbot -d config.json
  164. Join that channel and give commands to the bot::
  165. ~fetchdb http://paste.openstack.org/raw/755522/
  166. #swift now discussing ring placement
  167. (note, the bot currently only takes commands from Freenode identified users)
  168. In another terminal, start the webserver::
  169. cd html && python -m SimpleHTTPServer
  170. Open the web page in a web browser: http://127.0.0.1:8000/ptg.html