Table of Contents

1. List of Commands
2. Module Development
3. Managing MirahezeBot (for maintainers)
4. 1. Restarting MirahezeBot
   2. Improving Modules
   3. Configuration Changes
   4. Canceling Reminders
   5. Website Updates

List of Commands

Plugin Development

If you decided to extend MirahezeBot with some functionality, you will need to create a new module.
This instruction will guide you through the process of custom plugin development
First of all, create a new file in modules directory with name your_module.py
Bot modules are python scripts, so we shall start with importing required libraries (bot is using sopel) for your module to work. Here is the list of imports typically used:

    from __future__ import unicode_literals, absolute_import, print_function, division
    import sopel
    import sopel.module
    import requests
    import sopel.tools
    from sopel.module import rule, priority, thread, commands, example
    

Let's define a function, which replies to ".hi" command with a greeting:

    @commands('hi')
    def bot_hi(bot, trigger):
        bot.say('Hi ' + trigger.nick + '!')
    

Explanation: using @commands we specify which command bot should react to (in our case ".hi")
Handler function has two parameters:

• bot - bot instance, we use it to interact with chat (i.e. to send messages)
• trigger - provides us info about incoming command (text, sender, etc)

So in our example, we use bot.say to send message to the chat saying "hi, your_name!"
This is minimum required code for your module to function. You may try running it now.

Unluckily, our bot will react only to ".hi" messages, but you may want it to react to ".hello" and ".hey" as well
In order to achieve that, we may set multiple command variations bot will respond to by specifying all of them in the decorator:

    @commands('hi', 'hello', 'hey')
    def bot_hi(bot, trigger):
        bot.say('Hi ' + trigger.nick + '!')
    

You may try running that code and see that bot will react to all commands mentioned by saying "hi" to message sender.
Finally, you may want bot to accept some input from user. To demonstrate how to achieve that, let's develop a function which will welcome chat newcomers
For example, if John joins your chat, you may ask bot to welcome him with command ".welcome John" and bot will send a message saying "Welcome, John! Enjoy yourself in this chat!"
Similarly, you may ask bot to welcome Bob my saying ".welcome Bob" and bot will say "Welcome, Bob! Enjoy yourself in this chat!"
Let's also use @example decorator to provide command usage example:

    @commands('welcome')
    @example('.welcome John')
    def bot_welcome(bot, trigger):
        bot.say('Welcome ' + trigger.group(2) + '! Enjoy yourself in this chat!')
    

Explanation: we use trigger.group(2) to get the text after the command (in our example - name of user to welcome)

Additionally, you may use bot.reply, which is similar to bot.say, but puts message sender name in the beginning of the message
To demonstrate that, let's create an "echo" function - it will send back to you your message, which will be starting with you name (i.e mention you):

    @commands('echo')
    @example('.echo hello world!')
    def bot_welcome(bot, trigger):
        bot.reply('You said: ' + trigger.group(2))
    

That was an example of simple module. We recommend you visiting Sopel Wiki for more info on this topic.

Complete source code of this example (file simple_module.py):

    from __future__ import unicode_literals, absolute_import, print_function, division
    import sopel
    import sopel.module
    import requests
    import sopel.tools
    from sopel.module import rule, priority, thread, commands, example

    @commands('hi', 'hello', 'hey')
    def bot_hi(bot, trigger):
        bot.say('Hi ' + trigger.nick + '!')


    commands('welcome')
    @example('.welcome John')
    def bot_welcome(bot, trigger):
        bot.say('Welcome ' + trigger.group(2) + '! Enjoy yourself in this chat!')


    @commands('echo')
    @example('.echo hello world!')
    def bot_welcome(bot, trigger):
        bot.reply('You said: ' + trigger.group(2))
    

Managing MirahezeBot (for maintainers)

Restarting MirahezeBot

To restart the bot first ssh to 100.node4.net.fosshost.org.

ssh (your username)@100.node4.net.fosshost.org

Run the following command:

(your username)@100:~$ sudo service [mirahezebotprodlibera|mirahezebottestlibera] [start|stop|restart]

Improving Modules

See https://wiki.mirahezebots.org/wiki/Deploying_Changes

Configuration Changes

1. ssh into the server
2. cd into /srv/sopelbots/[test|prod]
3. Make any necessary changes to the config by editing libera.cfg (ie: nano libera.cfg or vim libera.cfg) and save the file.
4. Restart the bot using the guide above.

Canceling Reminders

To cancel a reminder first connect to the server.

ssh (your username)@100.node4.net.fosshost.org
(your username)@100:~$

Next cd into /srv/sopelbots/[test|prod] and edit libera.reminders.db and remove the entry for the reminder you want to cancel, and save the file.

(your username)t@100:~$ cd /srv/sopelbots/[test|prod]
(your username)@100:~/.sopel$ nano libera.reminders.db

Finally, follow the guide to restart the bot above.

Website Updates

For most changes, simply merging will deploy within ~10 mins. If you can not use auto-deploy or it is down, merge your change on GitHub. Next ssh to the server.

ssh (your username)@100.node4.net.fosshost.org

Next run puppet. This will pull in any new changes to the repository on GitHub.

(your username)@100:~$ puppet-run

Go to mirahezebots.org and check to make sure your changes are present. If not ask MacFan4000, or RhinosF1 to clear the cache on Cloudflare.