API versioning and docker releases

[LK4D4]

Ok, here my thoughts about api versioning.

1. Using semver notation for docker
2. Using vMAJOR.MINOR or even vMAJOR as version for api
3. Different subrouters for different api versions: /v1.1/logs, /v1.2/logs...
4. Different codebases(including unittests, which is very important in that
   case) for different api versions, for example all stable api functions in
   api/server have _<version> suffix.
5. Not breaking api in patch or may be even in minor versions
6. Different branches for fixing and for development. I'm pretty excited about
   gitflow
7. More sophisticated release procedure. For example using gitflow:
   • copy current development api with version bump in routes
   • mark api as stable(add suffix to functions)
   • deprecate very old api versions(may be three releases from now or so, dunno)
   • create release branch from develop
   • make beta packages for volunteer's testing
   • fix bugs in release branch
   • merge release branch in master and develop
   • make tag from master
   • RELEASE THE MOBY DOCK
8. Hotfixes procedure. Hotfixes doesn't bring any new features. If we want new
   feature very much(for example someone want it and ready to pay 1 million :)) we
   just do new release. Hotfixes bumps patch version.

What are you think about it?
ping @discordianfish @shykes @crosbymichael @vieux

[discordianfish]

Those look to me like different concerns: Versioning and docker releases. Maybe make two issues from that?

Regarding the versioning I don't really care about how to implement it (global versions vs versioned components vs backward compatible components), I just assume that:

1. Even after 1.0 there will be fundamental changes to the api like moving parameters between host and run config.
2. People will run very old (years) versions of docker and latest releases and need to use the same client for both. If they have to use different client versions this will be reason for frustration and hinder adoption.
3. People will run older (months) versions of docker and latest releases in the same 'cluster', their cluster manager needs to support all versions of docker in the cluster. Keeping different client (cluster manager) around isn't even possible in that case.
4. Pushing out the burden of supporting different docker versions to the clients will multiply the necessary work (one implementation per client(library), not one in the docker daemon) and cause fragmentation in the 'docker client' ecosystem.

Which leads me to the conclusion that we need to support older clients somehow and I would recommend to not require the clients to implement different behavior based on the docker daemon's version.

[discordianfish]

Those look to me like different concerns: Versioning and docker releases. Maybe make two issues from that?

Regarding the versioning I don't really care about how to implement it (global versions vs versioned components vs backward compatible components), I just assume that:

1. Even after 1.0 there will be fundamental changes to the api like moving parameters between host and run config.
2. People will run very old (years) versions of docker and latest releases and need to use the same client for both. If they have to use different client versions this will be reason for frustration and hinder adoption.
3. People will run older (months) versions of docker and latest releases in the same 'cluster', their cluster manager needs to support all versions of docker in the cluster. Keeping different client (cluster manager) around isn't even possible in that case.
4. Pushing out the burden of supporting different docker versions to the clients will multiply the necessary work (one implementation per client(library), not one in the docker daemon) and cause fragmentation in the 'docker client' ecosystem.

Which leads me to the conclusion that we need to support older clients somehow and I would recommend to not require the clients to implement different behavior based on the docker daemon's version.

[LK4D4]

@discordianfish Here I've described how we can organize release process to support old api versions with one big pain on releases, instead of continuous pain in development.

[LK4D4]

@discordianfish Here I've described how we can organize release process to support old api versions with one big pain on releases, instead of continuous pain in development.

[thaJeztah]

Here's something I wrote-up a while ago. Not all parts are very well thought out, but it echoes my concerns at the time regarding Dockerfiles and compatibility; #4907

[thaJeztah]

Here's something I wrote-up a while ago. Not all parts are very well thought out, but it echoes my concerns at the time regarding Dockerfiles and compatibility; #4907

[LK4D4]

looks like old

[LK4D4]

looks like old