Usergrid release process

[Rod Simpson <ro...@rodsimpson.com>]

Team,

I would like to start a discussion of the Usergrid release process.  Licenses are being added and we are getting close to a point where we could do an official release.

In this thread, I specifically want to discuss the following: how will we handle versioning?  

Usergrid is a project of projects.  We have many SDKs, the Admin Portal, UGC, and of course, the Stack.  So what I am thinking about is how all these disparate projects will be tagged with version numbers and released.

Although we may do an initial 1.0 (or maybe 2.0?) release that contains every sub-project, it seems difficult or possibly pointless to try to keep them all on the same release cadence.  Developers will get work done on the different sub-projects when they have time or when they have the need.  This means that each sub-project will tend progress at its own pace. 

The question then, is how do we ensure version compatibility between projects (e.g. how do I know that version 1.2.3 of an SDK will work with 1.3.5 of the stack)?

Except for new features that we add, our API is quite stable.  The API is the interface between all SDKs/the Admin Portal/UGC, and the Stack. This means that old versions of the SDKs or the Admin Portal or UGC will work with new versions of the Stack.  In fact, except for one or two situations where we coded around issues in the Stack, SDK versions from 2 years ago would run against the current build of the Stack.

It is a little more challenging if you go the other way.  Newer versions of the SDK may have code to support features that may not have been implemented in older versions of the Stack.  

Question 1: how to we track this?

I am thinking that each sub-project should have a page on the website where this information is displayed. The Stack merely needs to exhibit a version number.  The SDKs, Admin Portal, and UGC all need to state the version of the Stack they are backwards compatible with.  Remember, old SDK versions will work with new versions of the Stack, but new SDK versions may not work with old versions of the Stack.

Question 2: how do we decide that a version of the code is ready for a version increment?

I propose that the workflow that might look something like this:

1.	Developer works on code, checks in 1 or more PRs.
2.	Developer (or other committer) decides that the code that merits a  version increment.
3.	Developer (or other committer) proposes discussion of such on the Dev ML.
4.	Once appropriate discussion has occurred, the originator calls for a vote (on a VOTE thread).
5.	If vote is accepted (I think it takes 3 +1 votes?), the originator submits another PR to increment the version number wherever it is being tracked.
6.	Once acked, the build is published to the appropriate page on the website along with version compatibility (and whatever other administrivia needs to occur).


This workflow would allow each sub-project to progress at its own pace.  It also lets discussion occur prior to a version increment.  And finally, it means the sub-projects don’t impact one another unnecessarily. 



Thoughts?


-- 
Rod Simpson
@rockerston
rodsimpson.com

Re: Usergrid release process

[Lieven Govaerts <lg...@apache.org>]

Hi,

On Mon, Apr 7, 2014 at 7:08 AM, Rod Simpson <ro...@rodsimpson.com> wrote:
> Team,
>
> I would like to start a discussion of the Usergrid release process.  Licenses are being added and we are getting close to a point where we could do an official release.
>
> In this thread, I specifically want to discuss the following: how will we handle versioning?
>
> Usergrid is a project of projects.  We have many SDKs, the Admin Portal, UGC, and of course, the Stack.  So what I am thinking about is how all these disparate projects will be tagged with version numbers and released.
>
> Although we may do an initial 1.0 (or maybe 2.0?) release that contains every sub-project, it seems difficult or possibly pointless to try to keep them all on the same release cadence.  Developers will get work done on the different sub-projects when they have time or when they have the need.  This means that each sub-project will tend progress at its own pace.
>

Are you suggesting that each of these sub projects can release
independently? Or that you make Usergrid releases, where some but not
necessarily all sub projects have new features/fixes?

Your repository is now set up to make releases for the whole project,
so I guess it's the latter option. This lays down a release cadence
for all sub projects. This doesn't mean automatically that all SDK's
have to stay in sync with versions of the stack (or is this a
guarantee the project wants to make?), just that SDK's have to be
ready to release when the stack+API is released.

> The question then, is how do we ensure version compatibility between projects (e.g. how do I know that version 1.2.3 of an SDK will work with 1.3.5 of the stack)?
>
> Except for new features that we add, our API is quite stable.  The API is the interface between all SDKs/the Admin Portal/UGC, and the Stack. This means that old versions of the SDKs or the Admin Portal or UGC will work with new versions of the Stack.  In fact, except for one or two situations where we coded around issues in the Stack, SDK versions from 2 years ago would run against the current build of the Stack.
>
> It is a little more challenging if you go the other way.  Newer versions of the SDK may have code to support features that may not have been implemented in older versions of the Stack.
>
> Question 1: how to we track this?
>
> I am thinking that each sub-project should have a page on the website where this information is displayed. The Stack merely needs to exhibit a version number.  The SDKs, Admin Portal, and UGC all need to state the version of the Stack they are backwards compatible with.  Remember, old SDK versions will work with new versions of the Stack, but new SDK versions may not work with old versions of the Stack.
>

This assumes that an SDK being backwards compatible with a specific
release of the stack+API is an all-or-nothing story. Another option is
to make it explicit which features the stack supports - by giving them
names - and then creating an API (e.g. using an OPTIONS request) that
allows the SDK to check with the server which features it supports.
This does not have to be done for all features of course, just for
those that require extra support on the client side.

The benefit of this approach is that if a stack version implements
multiple new features, SDK releases can incrementally add these new
features one by one.   Also, in the SDK code, you won't have those
difficult to understand "if server_ver > 100 and server_ver < 110"
blocks.

The compatibility table you put on the website can then be something like:
feature   / required version -> | stack | ruby sdk  | javascript sdk
     | ...
feature_XYZ                           | 1.1.0  |    1.0.1    | not
implemented   | ...

IMHO this gives a much clearer message to developers than just using
version numbers. Also, keeping it in one table makes it visible when
SDK's don't implement the features of the latest stack yet.

> Question 2: how do we decide that a version of the code is ready for a version increment?
>
>
> I propose that the workflow that might look something like this:
>
> 1.      Developer works on code, checks in 1 or more PRs.
> 2.      Developer (or other committer) decides that the code that merits a  version increment.
> 3.      Developer (or other committer) proposes discussion of such on the Dev ML.
> 4.      Once appropriate discussion has occurred, the originator calls for a vote (on a VOTE thread).
> 5.      If vote is accepted (I think it takes 3 +1 votes?), the originator submits another PR to increment the version number wherever it is being tracked.
> 6.      Once acked, the build is published to the appropriate page on the website along with version compatibility (and whatever other administrivia needs to occur).
>

In my experience, the procedure can depend on what type of change has been made:
- Adding new features to the stack that can only be used when also
implemented in the SDK, won't need a formal VOTE. Just add the feature
to the list and update the documentation. Everything is logged via
commit mails, so people can discuss or object if needed.
- Making a backwards-compatibility breaking change in the stack is a
different story. If you plan to use/are using semantic versioning
(major.minor.patch), this should require a change in the major
version. The impact can be quite big, so it should require a consensus
between the developers (can be done via normal release discussion and
voting).
- Making changes to the SDK's: increment minor version for new
features and patch version for fixes only. Major versions increments
can then be used for breaking changes to the API of the SDK.

>
> This workflow would allow each sub-project to progress at its own pace.  It also lets discussion occur prior to a version increment.  And finally, it means the sub-projects don't impact one another unnecessarily.
>
>
>
> Thoughts?
>
>
> --
> Rod Simpson
> @rockerston
> rodsimpson.com

Lieven