Mailing-List: contact user-help@avro.apache.org; run by ezmlm
Precedence: bulk
Reply-To: user@avro.apache.org
User-Agent: Microsoft-MacOutlook/14.13.0.110805
Date: Tue, 29 Nov 2011 10:22:32 -0800
Subject: Re: Best practice for versioning IDLs?
From: Scott Carey <scottcarey@apache.org>
Sender: Scott Carey <scott@richrelevance.com>
To: "user@avro.apache.org" <user@avro.apache.org>
Message-ID: <CAFA6010.6165A%scott@richrelevance.com>
Thread-Topic: Best practice for versioning IDLs?
In-Reply-To: <4ED51452.3090105@aol.com>
Mime-version: 1.0
Content-type: text/plain;
	charset="US-ASCII"
Content-transfer-encoding: 7bit

I don't think there are yet best practices for what you are trying to do.

However, I suggest you first consider embedding the version as metadata in
the schema, rather than data.  If you put it in a Record, it will be data
serialized with every record.  If you put it as schema metadata, it will
only exist in the schemas and not the data.

In raw JSON schema form, the metadata can be added to any named type:
Record, Fixed, Enum, Protocol.   The "doc" field is a special named
metadata field, you can use it or add your own:

{
  "namespace": "com.acme",
  "protocol": "HelloWorld",
  "doc": "Protocol Greetings",
  "acme.version": "1.22.3",

  "types": [
    {"name": "Greeting", "type": "record", "fields": [
      {"name": "message", "type": "string"}]},
    {"name": "Curse", "type": "error", "fields": [
      {"name": "message", "type": "string"}]}
  ],

  "messages": {
    "hello": {
      "doc": "Say hello.",
      "request": [{"name": "greeting", "type": "Greeting" }],
      "response": "Greeting",
      "errors": ["Curse"]
    }
  }
}

http://avro.apache.org/docs/current/spec.html#Protocol+Declaration

For IDL, it should be possible to add a property using the
@propname("propval") annotation on the protocol.
http://avro.apache.org/docs/current/idl.html#defining_protocol

I have not tried this myself however.

If I had the setup to test it now, I would try to see if the below AvroIDL
creates an empty protocol with the "acme.version" property set:

@acme.version("1.22.3")
@namespace("com.acme")
protocol HelloWorld {

}


On 11/29/11 9:20 AM, "George Fletcher" <gffletch@aol.com> wrote:


>
>  
>
>    
>  
>  
>    Hi,
>      
>      I'd like to incorporate a semver.org style versioning structure
>      for the IDL files we are using. The IDLs represent interfaces of
>      services (ala SOA).
>      
>      We currently manage our IDL files separately from the
>      implementation as multiple services might use the same IDL. This
>      makes it critical to have the IDL's understand their version. I'd
>      like to see our build process be able to inject into the IDL the
>      version from the build environment (currently maven). Another
>      option would be to define the version within the IDL. However, the
>      only way I can think of to do this, is to create a "Version"
>      Record within each IDL and then maybe have the Record contains 3
>      string fields (major, minor, patch).
>      
>      Just wondering if there are any best practices already established
>      for this kind of IDL versioning.
>      
>      Thanks,
>      George
>