changeset 19:40ad0e7bc0f0

Add topics
author David Demelier <markand@malikania.fr>
date Tue, 19 Apr 2016 10:43:46 +0200
parents 69765ef67e86
children f9e3094aca59
files CMakeLists.txt documentation.md topics/versioning.md
diffstat 3 files changed, 75 insertions(+), 4 deletions(-) [+]
line wrap: on
line diff
--- a/CMakeLists.txt	Mon Mar 14 09:06:02 2016 +0100
+++ b/CMakeLists.txt	Tue Apr 19 10:43:46 2016 +0200
@@ -24,8 +24,7 @@
 find_package(Pandoc REQUIRED)
 
 # Some variables
-
-set(URL http://releases.malikania.fr/irccd/irccd-2.0.0.tar.xz)
+set(URL http://releases.malikania.fr/irccd/irccd-2.0.1.tar.xz)
 set(TEMPLATE ${irccd-web_SOURCE_DIR}/templates/template.html)
 set(TEMPLATE_DOC ${irccd-web_SOURCE_DIR}/templates/template-doc.html)
 set(OUTPUT ${CMAKE_BINARY_DIR}/html)
@@ -53,16 +52,34 @@
 )
 
 # Define the files to generate.
-set(FILES about contribute documentation documentation download index support)
+set(
+	FILES
+	about
+	contribute
+	documentation
+	documentation
+	download
+	index
+	support
+	topics/versioning
+)
 
 # Arguments for specific files.
 set(index_VARS home:yes)
 
 foreach (f ${FILES})
+	get_filename_component(OUTPUTDIR ${OUTPUT}/${f} DIRECTORY)
+	file(MAKE_DIRECTORY ${OUTPUTDIR})
+	file(RELATIVE_PATH baseurl ${OUTPUTDIR} ${OUTPUT})
+
+	if (baseurl STREQUAL "")
+		set(baseurl "./")
+	endif ()
+
 	pandoc(
 		OUTPUT ${OUTPUT}/${f}.html
 		SOURCES ${SOURCE}/${f}.md
-		VARIABLE baseurl:. ${${f}_VARS}
+		VARIABLE baseurl:${baseurl} ${${f}_VARS}
 		FROM markdown
 		TO html5
 		ARGS --no-highlight
--- a/documentation.md	Mon Mar 14 09:06:02 2016 +0100
+++ b/documentation.md	Tue Apr 19 10:43:46 2016 +0200
@@ -20,3 +20,7 @@
   - [logger](plugin/logger.html)
   - [plugin](plugin/plugin.html)
   - [roulette](plugin/roulette.html)
+
+## Additional topics
+
+  - [Versioning](topics/versioning.html)
\ No newline at end of file
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/topics/versioning.md	Tue Apr 19 10:43:46 2016 +0200
@@ -0,0 +1,50 @@
+---
+title: "IRC Client Daemon - Versioning"
+---
+
+<div class="page-header">
+ <h1>Versioning</h1>
+</div>
+
+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/
\ No newline at end of file