From df7e8848d319b36ec5ba54633770f257269569e5 Mon Sep 17 00:00:00 2001
From: Jeremy Stanley <fungi@yuggoth.org>
Date: Mon, 10 Jul 2017 22:46:53 +0000
Subject: [PATCH] Instructions for registering up a new IRC bot nick

In order to demystify some of the initial setup around IRC nick
registration for new bots, start a new section in the IRC
documentation page for a recommended workflow and gotchas.

Change-Id: Ica9f24b725cc2d4425741b383f788a537992f80d
---
 doc/source/irc.rst | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/doc/source/irc.rst b/doc/source/irc.rst
index 60218985d6..8b20196e0f 100644
--- a/doc/source/irc.rst
+++ b/doc/source/irc.rst
@@ -360,3 +360,42 @@ server that is operative. Switch the entries on /etc/hosts to choose
 the right one, and restart the service with:
 
     sudo service xxxbot restart
+
+Registering a Nick for a New Bot
+================================
+
+First and foremost, we use a separate alias for the ``infra-root@``
+E-mail address to distinguish the NickServ registration for each
+bot's nick. Presently, these E-mail alias additions must be
+requested from the OpenStack Foundation as they control the
+corresponding hosting account. This might take some time, so plan
+accordingly.
+
+Once you have the E-mail alias assigned, generate a lengthy (16+
+character) mixed-case alphanumeric string suitable as a NickServ
+registration password and record both of these pieces of information
+along with the nick in the secrets list for future reference.
+
+Now, use an IRC client you're comfortable with (possibly easier if
+you stick with default configuration rather than trying to do this
+from your normal client setup though) to temporarily connect with
+your newly chosen nick. For example, an unconfigured *weechat*
+client can be invoked as follows::
+
+  weechat irc6s://openstackbotname@chat.freenode.net:6697
+
+With the connection established, after you see the server MOTD echo,
+register the nick as follows::
+
+  /msg nickserv register some_strong_password email_alias
+
+You should hopefully get positive feedback from NickServ at this
+point, but don't disconnect yet. Moments later, the ``infra-root@``
+shared mailbox should contain a new message from Freenode support
+urging you to run the following additional command::
+
+  /msg nickserv verify register openstackbotname some_token
+
+This additional step completes the nick registration, though
+additional NickServ commands may be desirable to further secure the
+account against pranksters and ne'er-do-wells.