Determine version of spec

[rikvdh]

Hello,

It is not possible to determine a version of MessagePack from the spec. When using MessagePack in corporate applications it is preferred to refer to a specific version of the spec, in order to prevent incompatible changes in the spec which can affect end products. Referring to 'master' is not desirable since it is normally volatile.

In the tags of this repository I can not distinguish versions of the spec. However the website states a v5, but no v4, 3, 2 and 1 can be found.

Is it possible to tag specs etc?
How do all current existing tags relate to the spec?

Greetings,

Rik

[vonj]

I concur!

On April 10, 2015 11:38:43 AM CEST, Rik van der Heijden notifications@github.com wrote:

Hello,

It is not possible to determine a version of MessagePack from the spec.
When using MessagePack in corporate applications it is preferred to
refer to a specific version of the spec, in order to prevent
incompatible changes in the spec which can affect end products.
Referring to 'master' is not desirable since it is normally volatile.

In the tags of this repository I can not distinguish versions of the
spec. However the website states a v5, but no v4, 3, 2 and 1 can be
found.

Is it possible to tag specs etc?
How do all current existing tags relate to the spec?

Greetings,

Rik

---

Reply to this email directly or view it on GitHub:
#195

Skickat från min Android-telefon med K-9 E-post. Ursäkta min fåordighet.

[methane]

"MessagePack update proposal v5" means v5 of the "proposal", not the spec.

[methane]

• v5
• v4
• v3.5
• v3
• v2
• v1

[rikvdh]

All the gists state 'proposal'. But wouldn't it be a good idea to just 'tag' the spec in the repo here? And clearly elaborate on the version number in the spec itself.

The gist's were also not linked from the website. When I click in 'spec' on the website I am redirected to spec.md in master. But I can't determine version of this.

[methane]

While proposal have version number, it's not a version of spec.
All of proposal (v1, v2, ... v5) is for "new spec".

[rikvdh]

Ok,

• But what version is the current spec?
• Where are the old versions of the spec?
• Why is there no version numbering in the spec?
• How can enterprise applications use a specific 'version' of MessagePack without a possibility to refer to a version?

[methane]

But what version is the current spec?

"Current" or "New".

Where are the old versions of the spec?

https://github.com/msgpack/msgpack/blob/master/spec-old.md

Why is there no version numbering in the spec?

I think because @frsyuki doesn't want to modify spec in the future.

How can enterprise applications use a specific 'version' of MessagePack without a possibility to refer to a version?

"New spec" or "Old spec"

[methane]

FYI, new spec doesn't deprecate data created by old spec.
Decoders based on new spec can decode data encoded by encoders based on old spec.
Incompatible changes can't happen in msgpack. They have different name like BinaryPack.
So you can refer to msgpack/spec.md safely.

[vonj]

I am afraid this answer is just too open ended. I would be hesitant to use msgpack before and even more now, after this response.

What's the harm in adding a versioning scheme?

On April 10, 2015 1:02:43 PM CEST, INADA Naoki notifications@github.com wrote:

FYI, new spec doesn't deprecate data created by old spec.
Decoders based on new spec can decode data encoded by encoders based on
old spec.
Incompatible changes can't happen in msgpack. They have different name
like BinaryPack.
So you can refer to msgpack/spec.md safely.

---

Reply to this email directly or view it on GitHub:
#195 (comment)

Skickat från min Android-telefon med K-9 E-post. Ursäkta min fåordighet.

[xor-gate]

I totaly agree with vonj, protocol design MUST describe versioning with eventually incompatbilities and migration strategies between them. Look at IPv4/IPv6 etc.

If i rephrase what you say is that there is only a implicit version of MessagePack (msgpack) protocol? This is not desirable where a application or library needs to mention which specification or version of the protocol it implements. It is possible to get software architectures where applications and devices communicate with different versions of the protocol and get undefined behavior. Especially in Embedded (firmware) implementations.

[methane]

JSON also doesn't version number. Do you hesitate using JSON?

[xor-gate]

Still there is only one document for JSON and not 5 proposals of documents and a floating spec-old.md

[methane]

Proposal is proposal, not a spec.

[vonj]

I use it only with great care and because it has HUGE traction. Msgpack does not have that going for it. It is coming from an underdog position and it is a little bit better. Unless I get assurance from a versioning scheme this technical superiority is just not enough to go for a less tried protocol.

On April 10, 2015 2:14:08 PM CEST, Jerry Jacobs notifications@github.com wrote:

Still there is only one document for JSON and not 5 proposals of
documents and a floating spec-old.md

---

Reply to this email directly or view it on GitHub:
#195 (comment)

Skickat från min Android-telefon med K-9 E-post. Ursäkta min fåordighet.

[methane]

@frsyuki How about "old" and "final" as version scheme?

[methane]

When giving version scheme, we should separate "format" and "spec".
JSON format is stable, but have some specs (ECMA-404, RFC4627, RFC7158 and RFC 7159).

msgpack format is stable now, but specification will be improved.

[rikvdh]

But still, RFC's are a 'tag'. Changing the specification of JSON requires a new RFC. When you say in corporate applications you can say you support JSON (RFC7159). But when you want to support MessagePack, you can only refer to 'master', but master is no version.

When I today implement the current master and the spec is changed over a few month, my products specification implicitly change, but my implementation won't magically change.

Even all JSON RFC's and ECMA-404 have a date, which is already enough as a version-number, but having the head of a version-control-system as version makes the version volatile and this is not the meaning of a version.

[methane]

FYI, https://github.com/msgpack/msgpack/blob/master/spec.md is always describe final format.
tag is not required to refer format.

[xor-gate]

I think there is a duplicate issue over here same as subject of this issue: #162

[methane]

When I today implement the current master and the spec is changed over a few month, my products specification implicitly change, but my implementation won't magically change.

Do you mean fixing typo or adding example is problem for you?
I recommend you to use SHA-1.

If you say about changing format, master/spec.md always specifies one format.
There is no good commit for tagging.

[rikvdh]

But why can your implementations refer to an version of MessagePack?

https://github.com/msgpack/msgpack-c/blob/8455a2eb703b52672f75843f01dac52ddcf55aad/include/msgpack/version_master.h

This states a major of 0, and a minor of 6.

https://github.com/msgpack/msgpack-c/blob/master/include/msgpack/version_master.h

And this states a major of 1, and a minor of 1.

Probably things changed, and implementation refer to MessagePack with a version. Why not simply add a version to MessagePack spec. This will improve broader adoption in the community.

[methane]

This states a major of 0, and a minor of 6.
And this states a major of 1, and a minor of 1.

It's a library (msgpack-c) version, not a format version.

This will improve broader adoption in the community.

How? Why just using "old" to refer old spec is not enough?

[methane]

While I'm not @frsyuki, I'm -0.5 on adding version.

I would like to make msgpack like JSON. Fixing format is better than versioning format.
If we have "v2", many people will request "Please add XXX type in v3!".

[xor-gate]

I totally agree on having fixed format

[rikvdh]

Why don't you fix all typo's and submit this to IETF? When using MessagePack in SIL-4 applications the assessor shall accept an RFC, but not the head of a git repo as version.

[methane]

Does it relate to this issue?

While format is stable, polishing specification is not only fixing typos.
It may require a lot of time and energy.

[kuenishi]

-1 on putting any tags and versions to the spec - although I believe that depends on each library's maintainer. If all maintainers, including @frsyuki, that may happen.

Although, I don't think any of us are interested in submitting to IETF, as the original purpose of creating RFC is for multiple hardware vendors of in lower layers to agree on the spec and guarantee connectivity. That is why strict versioning and standardization were required.

MessagePack and other serialization format like JSON mostly work on top of TCP or as file format - where all of them are handled by software like kernel or databases. ORC, Thrift, Protocol buffers, Parquet, all of them have different strategy of (not) versioning formats. Why don't you just accept diversity?

Maybe it's a good time to just delete this repo and make a single file just uploaded on msgpack.org. A file in repo has versions but a single web page doesn't.

[kuenishi]

Also, it is guaranteed that objects serialised with old spec can be deserialised with new spec libraries (I dare not use the word 'compatible'), as the new spec was carefully designed by @frsyuki and all library maintainers carefully implemented new spec. That's why I believe no versioning is required. Also, I don't think any more changes to the spec happens, or required like @methane stated. With incompatible changes different name than MessagePack would be used. Given these points, is there any other problems with not having versions?

[vonj]

I was not sure if I was going to use msgpack before. Now, I am.

[firegurafiku]

@methane

I would like to make msgpack like JSON. Fixing format is better than versioning format.

I second that. To my mind, keeping MessagePack isomorphic to JSON is the best possible option. As long as JSON does not have multiple versions, there is no need for them in MessagePack, too.

@kuenishi

Although, I don't think any of us are interested in submitting to IETF ...

I'm with the minority who thinks that submitting an Internet-Draft is worth it. Let's suppose that one is designing a new application layer protocol or trying to improve an existing one, and they found that MessagePack fits their task nicely. They also want their work to eventually become an RFC; however, it's not possible to say, for example, “the payload is MessagePack-encoded, navigate to the GitHub to see the details” in an I-D, there must be the normative description to link to.

I agree that preparing such a draft is highly time-consuming, but it is not useless.

Maybe it's a good time to just delete this repo and make a single file just uploaded on msgpack.org. A file in repo has versions but a single web page doesn't.

Nice thing to do after the format is fixed. The copy should go to ietf.org 😄.

[gfx]

Any update about it?

I suggest the GraphQL style versioning: https://graphql.github.io/graphql-spec/

It uses year and month like "May 2019"; Or, "2019.05" may be better because of its sortability.

[timmc]

@frsyuki Would you be open to a PR marking the old spec as "version 2011" and the new one as "version 2013"?