From 87c0efb8d0e22839092b84bc0063151bb73131a1 Mon Sep 17 00:00:00 2001
From: Takatoshi Kondo <redboltz@gmail.com>
Date: Fri, 3 Apr 2015 14:07:00 +0900
Subject: [PATCH] Updated version 1.1.x api versioning.

---
 v1_1_cpp_versioning.md | 72 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 v1_1_cpp_versioning.md

diff --git a/v1_1_cpp_versioning.md b/v1_1_cpp_versioning.md
new file mode 100644
index 0000000..65dca70
--- /dev/null
+++ b/v1_1_cpp_versioning.md
@@ -0,0 +1,72 @@
+# API versioning on C++
+
+msgpack-c have introduced API versioning mechanism.
+
+## Macros
+
+### MSGPACK_DEFAULT_API_VERSION
+MSGPACK_DEFAULT_API_VERSION means the default version of msgpack-c API. The current value is 1.
+
+```C++
+#if !defined(MSGPACK_DEFAULT_API_VERSION)
+#define MSGPACK_DEFAULT_API_VERSION 1
+#endif
+```
+
+When you want to set MSGPACK_API_VERSION explicitly, give the macro value as follows:
+
+```
+g++ -DMSGPACK_API_VERSION=2
+```
+
+### MSGPACK_DEFAULT_API_NS
+
+MSGPACK_DEFAULT_API_NS is a namespace name of the default msgpack version. It names 'v' + MSGPACK_DEFAULT_API_VERSION. e.g.) v1, v2, ...
+
+It is used when you declare and define your custom overloads of operators.
+
+See the following example:
+
+https://github.com/msgpack/msgpack-c/blob/master/example/cpp03/class_non_intrusive.cpp#L47
+
+### MSGPACK_API_VERSION_NAMESPACE
+
+MSGPACK_API_VERSION_NAMESPACE is a function style macro. It defines a namespace. You can pass an argument as the namespace you want to define.
+
+```C++
+MSGPACK_API_VERSION_NAMESPACE(v1) {
+   // ...
+}
+
+MSGPACK_API_VERSION_NAMESPACE(v2) {
+   // ...
+}
+```
+
+The macro is expanded to namespace. If the given namespace name is same as MSGPACK_DEFAULT_API_NS, the macro is expanded as follows:
+
+In the case MSGPACK_DEFAULT_API_NS == v1
+
+C++11
+
+```C++
+inline namespace v1 {
+   // ...
+}
+
+namespace v2 {
+   // ...
+}
+```
+
+C++03
+
+```C++
+namespace v1{}; using namespace v1; namespace v1 {
+   // ...
+}
+
+namespace v2 {
+   // ...
+}
+```