Mercurial > irccd
changeset 184:0ff84eeea2b0
Docs: move procedures to the wiki
author | David Demelier <markand@malikania.fr> |
---|---|
date | Wed, 01 Jun 2016 12:48:04 +0200 |
parents | 166f589e30e5 |
children | b5758826f5fc |
files | doc/CMakeLists.txt doc/procs/00.new-release.md doc/procs/00.tests.md doc/procs/10.new-plugin.md doc/procs/20.options.md doc/procs/30.options.md doc/procs/60.new-command.md doc/procs/README.md |
diffstat | 8 files changed, 0 insertions(+), 745 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/CMakeLists.txt Wed Jun 01 12:37:00 2016 +0200 +++ b/doc/CMakeLists.txt Wed Jun 01 12:48:04 2016 +0200 @@ -22,13 +22,6 @@ add_custom_target( all-docs ALL COMMENT "Building irccd documentation" - SOURCES - ${doc_SOURCE_DIR}/procs/README.md - ${doc_SOURCE_DIR}/procs/00.tests.md - ${doc_SOURCE_DIR}/procs/00.new-release.md - ${doc_SOURCE_DIR}/procs/20.options.md - ${doc_SOURCE_DIR}/procs/30.options.md - ${doc_SOURCE_DIR}/procs/60.new-command.md ) set_target_properties(
--- a/doc/procs/00.new-release.md Wed Jun 01 12:37:00 2016 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,54 +0,0 @@ -Releasing new version -===================== - -This procedure must be done before releasing a new irccd version. - -1. Switch to the appropriate release branch. - -Example, if about to release 2.0.5: - - $ hg update release-2.0 - -2. Change the version and date in the cmake/IrccdVersion.cmake file. - -Example: - - set(IRCCD_VERSION_MAJOR "2") - set(IRCCD_VERSION_MINOR "0") - set(IRCCD_VERSION_PATCH "5") - - set(IRCCD_RELEASE_DATE_YEAR 2016) - set(IRCCD_RELEASE_DATE_MONTH 12) - set(IRCCD_RELEASE_DATE_DAY 31) - -3. Update or verify the CHANGES.md file - -4. Update the README.md - -You must remove the "This is a development version" notice from the file and change the version. - -5. Change the version in the irccd guide. - -6. Create a new tag x.y.z - - $ hg tag 2.0.5 - -7. Create the signature of the tag - - $ hg sign - -8. Push the changes and merge by top-porting it - -Example: - - $ hg update stable-2 - $ hg merge release-2.0 - $ hg ci -m "Merge from release-2.0" - $ hg up @ - $ hg merge release-2.0 - $ hg ci -m "Merge from stable-2" - $ hg push - -9. Create the package - - $ make release
--- a/doc/procs/00.tests.md Wed Jun 01 12:37:00 2016 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,74 +0,0 @@ -Irccd test plan -=============== - -Use this file to test irccd in several ways where it can not be unit tested. - -Template: - -Action: -Expected: -Status: -Remarks: - -Status: - - - Ok, - - Incorrect. - -## Irccd command line options - -Action: -f must run in foreground and override configuration file (*) -Expected: irccd does not go to background -Status: Ok -Remarks: - -Action: -v must enable more messages -Expected: more messages appear -Status: Ok -Remarks: - -Action: -c must use the specified configuration file -Expected: irccd loads the specified file -Status: Ok -Remarks: - -(*) has no effect on Windows. - -## Irccdctl command line options - -Action: specifying -t must connect to the command line arguments, not the configuration -Expected: even if the configuration has a `[connect]`, irccdctl must connect to the command line arguments -Status: Ok -Remarks: - -Action: -v must enable more messages -Expected: more messages appear -Status: Ok -Remarks: - -## Irccdctl aliases - -Action: Given `x = ""`, the alias must not be loaded -Expected: error -Status: Ok -Remarks: - -Action: Given `x = "plugin-load %0"` typing `irccdctl x` should throw an error because argument is missing -Expected: error -Status: Ok -Remarks: - -Action: Given `x = ( "plugin-unload %0", "plugin-load %0" )` typing `irccdctl x ask` should unload and load ask -Expected: ask is unloaded and then loaded -Status: Ok -Remarks: - -Action: Given `x = "server-connect -n bertrand %1 %0"`, typing `irccdctl x host id` should execute `irccdctl server-connect -n bertrand id host` -Expected: the `id` and `host` paremeters are inverted thanks to %1 and %0 -Status: Ok -Remarks: - -Action: Given `x = "server-connect %0 %0"`, typing `irccdctl x localhost 7000` should execute `irccdctl server-connect localhost localhost 7000` -Expected: irccd tries to connect to localhost (id localhost too) on port 7000 -Status: Ok -Remarks:
--- a/doc/procs/10.new-plugin.md Wed Jun 01 12:37:00 2016 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,45 +0,0 @@ -Writing new plugin -================== - -This procedure let you bundle a new plugin within irccd. - -1. Create the plugin directory in plugins/plugin-name. - -2. Write the plugin JavaScript file - -The plugin file must be named exactly the same as the directory name plus the .js suffix. - -Example: - -- plugins/myplugin/myplugin.js - -3. Fill the plugin information. - -The plugin must have the **info** table set, see other plugins for example. - -````javascript -info = { - author: "Firstname Lastname <email>", - license: "Your license", - summary: "Short summary without period", - version: "The version" -}; -```` - -If the plugin is intended to be bundled with irccd, license must be set to **ISC** and the version to **@IRCCD_VERSION@**. - -3. Write the documentation file - -Just like the JavaScript file, it must be named the same plus the .md suffix. - -Example: - -- plugins/myplugin/myplugin.md - -Document your plugin using markdown, see other plugins and try to be as close as possible. - -4. Update cmake/IrccdVersion.cmake - -Add the canonical plugin name to the **IRCCD_PLUGINS** variable, that's it. - -Note: please keep the variable ordered. \ No newline at end of file
--- a/doc/procs/20.options.md Wed Jun 01 12:37:00 2016 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,89 +0,0 @@ -Irccd configuration file (irccd.conf) -===================================== - -This file describes how to add new options in the irccd configuration file. - -# Current options - -## general - - - **uid**: (string or number) the user id to use (Optional, default: none), - - **gid**: (string or number) the group id to use (Optional, default: none), - - **foreground**: (bool) set to true to not daemonize (Optional, default: false), - - **pidfile**: (string) path to a file where to store the irccd pid (Optional, default: none). - -## format - - - **debug**: (string) template to use to format debug messages (Optional, default: none), - - **info**: (string) template to use to format information messages (Optional, default: none), - - **warning**: (string) template to use to format warnings (Optional, default: none). - -## logs - - - **verbose**: (bool) be verbose (Optional, default: false), - - **type**: (string) which kind of logging, console, file or syslog (Optional, default: console). - -The options for **file** type: - - - **path-logs**: (string) path to the normal messages, - - **path-errors**: (string) path to the error messages. - -## identity - - - **name**: (id) the identity unique id, - - **nickname**: (string) the nickname (Optional, default: irccd), - - **realname**: (string) the realname (Optional, default: IRC Client daemon), - - **username**: (string) the username name (Optional, default: irccd), - - **ctcp-version**: (string) what version to respond to CTCP VERSION (Optional, default: IRC Client Daemon), - - **ctcp-autoreply**: (bool) enable auto CTCP VERSION reply, (Optional, default: true). - -## server - - - **name**: (id) the unique id, - - **host**: (string) the server address, - - **port**: (int) the server port (Optional, default: 6667), - - **identity**: (string) an identity to use (Optional, default: irccd's default), - - **password**: (string) an optional password (Optional, default: none), - - **auto-rejoin**: (bool) auto rejoin a channel after being kicked (Optional, default: false), - - **join-invite**: (bool) join channels upon invitation (Optional, default: false), - - **channels**: (list) list of channels to auto join, (Optional, default: empty), - - **command-char**: (string) the prefix for invoking special commands (Optional, default: !), - - **ssl**: (bool) enable or disable SSL (Optional, default: false), - - **ssl-verify**: (bool) verify the SSL certificates (Optional, default: true), - - **reconnect**: (bool) enable reconnection after failure (Optional, default: true), - - **reconnect-tries**: (int) number of tries before giving up. A value of 0 means indefinitely (Optional, default: 0), - - **reconnect-timeout**: (int) number of seconds to wait before retrying (Optional, default: 30). - -## plugins - -No options. - -## transport - - - **type**: (string) type of listener "ip" or "unix" - -The options for **ip** type: - - - **port**: (int) port number, - - **address**: (string) address to bind or "*" for any (Optional, default: *), - - **family**: (list) ipv6, ipv4. Both are accepted (Optional, default: ipv4). - -The options for **unix** type: - - - **path**: (string) the file path to the socket. - -## rule - - - **servers**, (list) a list of servers that will match the rule (Optional, default: empty), - - **channels**, (list) a list of channel (Optional, default: empty), - - **plugins**, (list) which plugins (Optional, default: empty), - - **events**, (list) which events (e.g onCommand, onMessage, ...) (Optional, default: empty), - - **action**, (string) set to **accept** or **drop**. - -# Add a new option - - 1. Update this file, - 2. Open irccd/config.cpp and load your option into the appropriate function, - 3. Update doc/html/guide/04-irccd/01-config.md, - 4. Update doc/examples/irccd.conf, - 5. Update doc/man/irccd.conf.5.in.
--- a/doc/procs/30.options.md Wed Jun 01 12:37:00 2016 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,24 +0,0 @@ -Irccdctl configuration file (irccdctl.conf) -=========================================== - -This file describes how to add new options in the irccdctl configuration file. - -# Current options - -## general - - - **verbose**: (bool) enable verbose message (Optional, default: false). - -## connect - - - **type**: (string) type of listener "ip" or "unix". - -The options for **internet** type: - - - **host**: (string) host to connect, - - **port**: (int) port number, - - **family**: (string) internet family: ipv6 or ipv4 (Optional, default: ipv4). - -The options for **unix** type: - - - **path**: (string) the file path to the socket.
--- a/doc/procs/60.new-command.md Wed Jun 01 12:37:00 2016 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,438 +0,0 @@ -All irccdctl commands -===================== - -This file groups all irccdctl commands, help messages so that it's easier to maintain the manual pages, HTML -documentation and command line help in case of change. - -This file can also been reviewed in case of spoken errors. - -Please update this file before updating any source code. - -All values that are marked optional MUST be silently discarded in the commands if they are not valid. - -# JavaScript API - -Whenever possible, if a function in the irccd's API is available, the arguments MUST be defined in the same order. For -example, the method `Server.cnotice` should have **channel**, **message** arguments. - -# Updating the code - -Adding a new transport command is quite straightforward. - -You need to create two classes: one as irccdctl request and one as irccd command. Both files must be named -`command-<name>.(h|cpp)`. - -# Irccd command - -To implement the command irccd's side, you must write a class like this: - -**command-mycommand.h** - -Inherit from `TransportCommand` and override the `exec` function. - - #include "transport-command.hpp" - - namespace irccd { - - namespace command { - - class MyCommand : public TransportCommand { - public: - void exec(Irccd &irccd, TransportClient &tc, const json::Value &object) const override - { - // Do what you want here - } - }; - - } // !command - - } // !irccd - -Then, in the `irccd` main.cpp file, register the new class using `Irccd::addTransportCommand` function. - -# Irccdctl command - -In irccdctl, you must implement two functions. One to show the usage when calling `irccdctl help` and the one to -execute. - -Inherit from `Command` and override both `usage` and `exec` functions. - - #include "command.hpp" - - namespace irccd { - - namespace command { - - class MyCommand : public Command { - public: - void usage(Irccdctl &irccdctl) const - { - // print the message using log::warning(). - } - - void exec(Irccdctl &irccdctl, const std::vector<std::string> &args) const - { - // send the command using irccdctl.send(). - } - }; - - } // !command - - } // !irccd - -And like irccd, you must register it in the `irccdctl` main.cpp file. - -# Updating the documentation - - 1. You must update doc/html/guide/05-irccdctl/02-commands.md to show the command usage, - 2. You must update doc/man/irccdctl.1.in to show the command usage too, - 3. You must update the appropriate command class in both irccd/irccdctl. - -**Note:** you must use the text from this file and propagate it to the files described above. - -# Server commands - -## server-cmode - -Change the mode of the specified channel. - -### Usage - -`irccdctl server-cmode server channel mode` - -### Arguments - - - **command**: (string) "server-cmode", - - **server**: (string) the server unique id, - - **channel**: (string) the channel, - - **mode**: (string) the argument. - -### Responses - - - An error if the server does not exist. - -## server-cnotice - -Send a message notice on a channel. - -### Usage - -`server-cnotice server channel message` - -### Arguments - - - **command**: (string) "server-cnotice", - - **server**: (string) the server unique id, - - **channel**: (string) the channel name, - - **message**: (string) the notice message. - -## server-connect - -Connect to a server. - -### Usage - -`server-connect [options] id host [port]` - -**Options:** - - - **-c, --command**: specify the command char, - - **-n, --nickname**: specify a nickname, - - **-r, --realname**: specify a real name, - - **-u, --username**: specify a user name, - - **-S, --ssl-verify**: verify SSL, - - **-s, --ssl**: connect using SSL, - -### Arguments - - - **command**: (string) "server-connect", - - **name**: (string) the server unique id, - - **host**: (string) the host address, - - **port**: (int) the port number (Optional, default: 6667), - - **ssl**: (bool) use SSL (Optional, default: false), - - **sslVerify**: (bool) verify SSL (Optional, default: false), - - **nickname**: (string) the nickname to use (Optional, default: irccd), - - **username**: (string) the user name to use (Optional, default: irccd), - - **realname**: (string) the real name to use (Optional, default: IRC Client Daemon), - - **ctcpVersion**: (string) the CTCP Version to answer (Optional, default: the irccd's version), - - **commandChar**: (string) the command character to use to invoke commands (Optional, default: !), - - **reconnectTries**: (int) the number of reconnection to try (Optional, default: -1), - - **reconnectTimeout**: (int) the number of seconds to wait before retrying to connect (Optional, default: 30). - -### Responses - - - An error if a server with the same name exists. - -## server-disconnect - -Disconnect from a server. - -If server is not specified, irccd disconnects all servers. - -### Usage - -`server-disconnect [name]` - -### Arguments - - - **command**: (string) "server-disconnect", - - **server**: (string) the server unique id (Optional, default: none). - -### Responses - - - An error if the server does not exist. - -## server-info - -Get server information. - -### Usage - -`server-info name` - -### Arguments - - - **command**: (string) "server-info", - - **server**: (string) the server unique id. - -### Responses - - - The following properties on success: - - **name**: (string) the server unique id, - - **host**: (string) the server hostname, - - **port**: (int) the port, - - **ipv6**: (bool) true if using IPv6, - - **ssl**: (bool) true if connection is using SSL, - - **sslVerify**: (bool) true if SSL was verified, - - **channels**: (string list) list of channels. - - **nickname**: (string) the current nickname in use, - - **username**: (string) the username in use, - - **realname**: (string) the realname in use. - - An error if the server does not exist. - -### Responses - - - An error if the server does not exist. - -## server-invite - -Invite the specified target on the channel. - -### Usage - -`server-invite server target channel` - -### Arguments - - - **command**: (string) "server-invite", - - **server**: (string) the server unique id, - - **target**: (string) the nickname to invite, - - **channel**: (string) the channel. - -## server-join - -Join the specified channel, the password is optional. - -### Usage - -`server-join server channel [password]` - -### Arguments - - - **command**: (string) "server-join", - - **server**: (string) the server unique id, - - **channel**: (string) the channel to join, - - **password**: (string) the password (Optional, default: none). - -### Responses - - - An error if the server does not exist. - -## server-kick - -Kick the specified target from the channel, the reason is optional. - -### Usage - -`server-kick server target channel [reason]` - -### Arguments - - - **command**: (string) "server-kick", - - **server**: (string) the server unique id, - - **target**: (string) the target nickname, - - **channel**: (string) the channel, - - **reason**: (string) the reason (Optional, default: none). - -### Responses - - - An error if the server does not exist. - -## server-list - -Get the list of all connected servers. - -### Usage - -`irccdctl server-list` - -### Arguments - - - **command**: (string) "server-list". - -### Responses - - - The following properties: - - **list**: (string list) the list of all server unique ids. - -## server-me - -Send an action emote. - -### Usage - -`irccdctl server-me server target message` - -### Arguments - - - **command**: (string) "server-me", - - **server**: (string) the server unique id, - - **target**: (string) the target or channel, - - **message**: (string) the message. - -### Responses - - - An error if the server does not exist. - -## server-message - -Send a message to the specified target or channel. - -### Usage - -`irccdctl server-message server target message` - -### Arguments - - - **command**: (string) "server-message", - - **server**: (string) the server unique id, - - **target**: (string) the target or channel, - - **message**: (string) the message. - -### Responses - - - An error if the server does not exist. - -## server-mode - -Set the irccd's user mode. - -### Usage - -`irccdctl server-mode server mode` - -### Arguments - - - **command**: (string) "server-mode", - - **server**: (string) the server unique id, - - **mode**: (string) the mode. - -### Responses - - - An error if server is specified and the server does not exist. - -## server-nick - -Change irccd's nickname. - -### Usage - -`irccdctl server-nick server nickname` - -### Arguments - - - **command**: (string) "server-nick", - - **server**: (string) the server unique id, - - **nickname**: (string) the new nickname. - -### Responses - - - An error if the server does not exist. - -## server-notice - -Send a private notice to the specified target. - -### Usage - -`irccdctl server-notice server target message` - -### Arguments - - - **command**: (string) "server-notice", - - **server**: (string) the server unique id, - - **target**: (string) the target, - - **message**: (string) the notice message. - -### Responses - - - An error if the server does not exist. - -## server-part - -Leave the specified channel, the reason is optional. - -Not all IRC servers support giving a reason to leave a channel, do not specify it if this is a concern. - -### Usage - -`irccdctl server-part server channel [reason]` - -### Arguments - - - **command**: (string) "server-part", - - **server**: (string) the unique server id, - - **channel**: (string) the channel to leave, - - **reason**: (string) the reason (Optional, default: none). - -### Responses - - - An error if the server does not exist. - -## server-reconnect - -Force reconnection of one or all servers. - -If server is not specified, all servers will try to reconnect. - -### Usage - -`irccdctl server-reconnect [server]` - -### Arguments - - - **command**: (string) "server-reconnect", - - **server**: (string) the server unique id (Optional, default: none). - -### Responses - - - An error if server is specified and the server does not exist. - -## server-topic - -Change the topic of the specified channel. - -### Usage - -`irccdctl server-topic server channel topic` - -### Arguments - - - **command**: (string) "server-topic", - - **server**: (string) the unique server id, - - **channel**: (string) the channel, - - **topic**: (string) the new topic. - -### Responses - - - An error if server is specified and the server does not exist.
--- a/doc/procs/README.md Wed Jun 01 12:37:00 2016 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,14 +0,0 @@ -Irccd procedures -================ - -The files in this directory are small instructions to help irccd's development. - -Files are prefixed by a number which is a specific category: - - - 0, release engineering - - 1, irccd's JavaScript plugins, - - 2, the irccd daemon, - - 3, the irccdctl utility, - - 4, the documentation process, - - 5, the build system within irccd, - - 6, miscellaneous.