versioning idea

[ldulcic]

enum OrbMode {
  ORB_MODE_UNSPECIFIED = 0;
  LEGACY = 1;
  SELF_SERVE = 2;
}

enum OrbType {
  ORB_TYPE_UNSPECIFIED = 0;
  PEARL = 1;
  DIAMOND = 2;
}

message OrbMetadata {
  string orb_id = 1;
  OrbType orb_type = 2;
  OrbMode orb_mode = 3;
}

• OrbMetadata is a replacement for AnnouncingOrbId message.
• OrbMetadata is the first message Orb sends to the App.
• App decides how to communicate with the Orb based on OrbMetadata.orb_mode field.
• Self Serve mode has all of its messages in self_serve.proto file.

Forward compatibility

If we decide to add a new mode, eg. Self Serve v2, we do this:

• Add new SELF_SERVE_2 option in OrbMode enum
• Add new self_serve_v2.proto file with corresponding messages for this mode

If app doesn't support a mode it received, it would prompt user to update the app to verify.

Backward compatibility

• We can add messages in self_serve.proto but only if they won't break the flow in old apps, every breaking change requires a new OrbMode
• We can only add fields to OrbMetadata message

[andronat]

JFYI putting v1 in the way it was before, is because protobuf linters suggest so. We are using buf which actually follows Google and FB best practices. I think we should stay on this path :/

Also, I think your concern is that we need to bump the version on every change. That's not the case. This v1 is only if we introduce breaking changes. We can add and augment the structs and messages here without changing the versions. The same for the enums. We just need to make sure that our clients are able to handle unknown states.

[andronat]

I'm not against this and I'm actually proposing the same here: 9df4605. Let's do it!

[ldulcic]

wrong commit hash? :D

[ldulcic]

@andronat continued this idea in #30