Added 'Glossary' and 'Extending the crate' sections

Signed-off-by: Bogdan Mircea <mirceapetrebogdan@gmail.com>

messages/README.md

@@ -1,8 +1,15 @@
 # messages
-The `messages` crate provides data structures representing the various messages used in Aries protocols. This `README` explores the architecture behind the crate and module organization, making implementing new messages/protocols easier.
+The `messages` crate provides data structures representing the various messages used in Aries protocols. This `README` explores the architecture behind the crate and module organization to clarify the individual pieces and design decisions within the crate.
+
+### Glossary
+- `message content`: represents the protocol specific set of fields of a message
+- `message decorators`: represents the decorator fields of a message not directly linked to the processing of a message within a protocol
+- `message family` / `protocol`: represents the name of an Aries protocol, irrespective of its version (the `present-proof` part of `https://didcomm.org/present-proof/1.0/propose-presentation`)
+- `message kind`: represents the name of a particular message within a specific protocol (the `propose-presentation` part of `https://didcomm.org/present-proof/1.0/propose-presentation`)
+- `message type`: refers to the fully defined type of the message (which can translate to an entire, functional, `@type` field of an Aries message); it is comprised of a `protocol`, `major version`, `minor version` and `message kind`.
 
 ### Message structure
-All messages, from all protocols and all versions, are part of the parent `AriesMessage` enum. The individual messages from a specific version of a specific protocol are then implemented in a cascade:
+All messages, from all protocols and all versions, are part of the parent `AriesMessage` enum. The individual messages from a specific version of a specific protocol are then implemented in a cascade, as follows:
 
 - AriesMessage
  - Connection
@@ -55,7 +62,7 @@ As a result, simple `serde` tagged serialization/deserialization is not sufficie
 We want to take the `@type` field and parse it to determine the exact protocol, version and message to process. The machinery is in place for that to happen through the delayed serialization/deserialization, but the protocol version resolution and all the possible variants for the `@type` field are located within
 this module and encapsulated in the `Protocol` enum.
 
-Similarly to `AriesMessage`, the `Protocol` enum is represented in a cascading fashion:
+Similarly to `AriesMessage`, the `Protocol` enum is represented in a cascading fashion such as:
 
 - Protocol
  - ConnectionType
@@ -81,4 +88,21 @@ The relevant submodule then contains the actual definitions of the `content` and
 ### The `decorators` module
 Contains data structure for decorators. 
 
-Unlike messages and their `@type` field, decorators get their version associated within their name `~thread/1`. Since only major versions are used, swapping a decorators version in a message represents a breaking change and would have to be explicitly defined in the message's content/decorators data structure. No resolution is required.
+Unlike messages and their `@type` field, decorators get their version associated within their name `~thread/1`. Since only major versions are used, swapping a decorators version in a message represents a breaking change and would have to be explicitly defined in the message's content/decorators data structure. No resolution is required.
+
+### Extending the crate
+Adding new messages to the crate should be fairly easy to do, even without understanding all the inner workings. The main concepts needed are: 
+- the `AriesMessage` enum encapsulates all messages
+- messages are serialized/deserialized conditionally based on their `@type` field.
+- the `@type` field gets deserialized using the `Protocol` enum, through which all
+supported protocols can be resolved.
+- the `PROTOCOL_REGISTRY` contains entries for all supported protocol versions, which is how minor version resolution is handled
+
+With that in mind, a crude list of steps for extending the crate would be:
+- changes in the `msg_types` module
+ - adding/extending data types to represent the new protocol / protocol version
+ - if adding the first version of a new protocol, extend the `Protocol` enum
+ - add an entry to the `PROTOCOL_REGISTRY`
+- changes in the `msg_fields` module
+ - adding/extending data types to represent the message content and message decorators
+- if adding the first version of a new protocol, extend the `AriesMessage` enum