% irccd - versioning
% David Demelier <markand@malikania.fr>
% 2019-07-10

Versioning
==========

Irccd follows [Semantic Versioning][semver] for the following components.

Configuration file
------------------

The configurations files **irccd.conf** and **irccdctl.conf** MUST stay
compatible all the lifetime of a major version. If a configuration file is
created for irccd 2.4.5, then it MUST always work with irccd 2.8.0.
Compatibility may be altered in the next major version.

Deprecation of configuration options is allowed and noted as well in related
documentation. The user is encouraged to change its configuration files.

Javascript API
--------------

The provided Javascript API MUST remain compatible as well all the lifetime of a
major version.

It is possible to update existing functions as they don't break backward
compatibility such as:

- Adding a new parameter at the end of arguments,
- Returning an object while the function was returning undefined formerly,
- Throwing new kind of exception, Javascript has no by-type exception handling
  so this does not break user code,
- Taking a different parameter type as long as the other signature remains valid.

Plugins
-------

All plugin configurations are subject to the same terms as irccd configuration
files.

In additions to the configurations, each plugin MUST keep backward compatible
usages when invoking commands. Adding new arguments and features is possible in
minor versions.

Plugin message formats MUST still exist until the next major version but they
MAY write different messages in any new version. This is intentional as they can
contain typos. Users SHOULD NOT parse default formatted messages if this is a
concern.

Socket transport protocol
-------------------------

The network messages for communicating with irccd daemon MUST be backward
compatible in any new minor or patch versions.

Depractions of commands MUST be documented and an alternative SHOULD be proposed
to the user if applicable. Irccd stay silent in network responses when issuing
deprecated commands so the user SHOULD read the **CHANGES.md** from the project
directory or announcements from time to time.

Adding new properties in JSON object **is not** considered as a breaking change.

Build system
------------

All user definable options in irccd CMake build system MUST remain valid until
the next major version.

New options MAY be added in new minor versions. Deprecated options are noted as
well in annoucements or **CHANGES.md**.

[semver]: http://semver.org/