See RELEASE.md.

Circe should work best on the current major release of Emacs. It should work at all with the last major release of Emacs.

As of 2016-06-19, this means:

• Emacs 24 (latest release) should work flawlessly and have sane defaults. This is the main concern.
• Emacs git should also work.

Older versions (23 and earlier) are simply not relevant to Circe anymore.

To extend Circe for other purposes than those features in the core you have to write an extension module.

There are only few requirements for extension modules. A hypothetical grovel module should be provided in a circe-grovel.el file. This file needs to provide the circe-grovel feature, and two commands, named enable-circe-grovel and disable-circe-grovel. What those commands do is up to you.

It is also advisable that the enable function be annotated with an autoloads line.

The extension modules should not use minor modes. When a number of modules are loaded, any major mode help buffer is croweded with those useless minor modes which add no information. The enable/disable convention of Circe does not clutter the minor mode list.

Networks are defined in circe-network-defaults, which is an alist mapping a network name to a plist of options. The absolute minimum to add would be hostname, port and TLS support information. For example, 2600net uses "irc.2600.net" as hostname, permits plaintext connections on port 6667, TLS connections on port 6697 and defaults to using TLS:

("2600net" :host "irc.2600.net" :port (6667 . 6697) :tls t [...])

The port specification is either just the port number (in the case of plaintext-only servers) or a cons cell pairing the port number for plaintext and TLS service together. A TLS-only service would therefore put nil into the head of the pair.

To add NickServ support, it's necessary to enable IRC debug logs first:

(setq irc-debug-log t)

Connect to your network of choice and inspect both the server buffer and the "IRC Protocol :" buffer closely.

If you have no account yet, identify how to talk to NickServ or the equivalent service. On modern IRC networks, you'll see an IRC notice originating from the service asking you to register your nickname. Take a good look at the sender of the notice, this will be :nickserv-mask. Make sure to both anchor the value (by surrounding it with "^...$") and escape all dots (for example "example\\.net"). If you're not messages by NickServ, you can try your luck with /msg NickServ help or look up documentation. Some networks call it differently, some do not have an accounts management bot at all.

Next: Start a conversation with the service. Register an account if you haven't already and inspect the help of the IDENTIFY and GHOST (not always available, to not be confused with RECOVER, which undoes registration) commands. Take a good look at their syntax, specifically whether they need both nickname/password and if yes, in which order. This is translated to the :nickserv-identify-command and :nickserv-ghost-command options. For example, /msg NickServ IDENTIFY myuser hunter2 is translated to PRIVMSG NickServ MSG :IDENTIFY {nick} {password}.

After having registered an account, observe what text NickServ sends you if you connect with the corresponding nickname. This can be done by logging out, changing to an unused nickname and changing to the regular nickname (alternatively, by reconnecting). It will print a notice resembling something like "This nickname is registered.". Inspect the protocol log to find the most specific string in this challenge and turn it into a regular expression. For example, if there's always a notice starting with the previous phrase, you can translate that to "^This nickname is registered\." and put it into :nickserv-identify-challenge.

After identification, there should be a notice of the "You are now identified." kind. This again is translated to a regular expression and put into :nickserv-identify-confirmation. For example the previous one would be turned into "^You are now identified\.". The reason the protocol buffer is consulted for this, is that it clearly shows where strings start/end and control characters are displayed untranslated. This makes it easier to find the correct escape codes, if you choose to match against messages with formatting.

Finally, the ghost command is used when the desired nickname is not available. In this case, :nickserv-ghost-command is sent to NickServ if configured. The response to that is matched with :nickserv-ghost-confirmation to tell whether the command was successful. You can test this scenario by identifying with another client first, then connecting with Circe and observing the ghost command in action.