Version Numbering

[Jeff Kletsky]

On 3/23/15 12:20 AM, John Ralls wrote:
> What about API breaks in the Scheme and Python bindings? Not something 
> most users care about, but folks with custom scripts sure do. We've 
> always said that we don't guarantee API stability between major 
> versions, but we also promote the bindings pretty heavily.
>
> I suspect that users care most about file compatibility. We've done 
> pretty well on that through the 2.x series, but along with multi-user 
> will come a shift from default XML to default SQL, and going forward 
> from that we'll want to normalize the schema, especially to move stuff 
> out of slots.
>
> The two combined would be a useful guideline: first-number changes 
> mean that you'll have to revisit your scripts or your database will be 
> upgraded so that it's not readable by the previous version except the 
> closeout release.


 From a consumer perspective, as well as speaking as a product manager 
for enterprise software, I generally expect that (after the database 
upgrade has run):

* Major version number release
     * Meaningful improvement in functionality
     * Database schema may have changed and *likely not* be even 
readable by previous versions of software with the previous major 
version number (even in last of prior major version's releases)
     * API may have changed extensively, and may not be backwards 
compatible

* Minor version number release
     * Some improvement in functionality beyond bug fixes
     * Database schema may have changed and *may not* be read/write 
compatible with previous versions of software with the same major/minor 
version number.
     * API may have been extended and certain features may have been 
deprecated (but still functional)

* "Point" release
     * Primarily bug fixes
     * Database schema may have changed, but still read/write compatible 
with previous versions of the software with the same major/minor version 
number.
     * API may have been extended and certain features may have been 
deprecated (but still functional)

If a non-backwards-compatible database schema change is absolutely 
required for a point release, I'd consider first making it a minor 
release. If that wasn't appropriate, very clear messaging in the app 
prior to running the database upgrade, along with prominent information 
in the release notes would be my approach.



Going along with this are the usual tenants of using mission-critical 
software:

* It is the user's responsibility to back-up data before upgrading 
(though I don't object to a warning before running the database upgrade 
triggers)

* It is the user's responsibility to test, evaluate, and consider the 
impact of upgrading to a new major version to determine if it provides 
benefits sufficient to outweigh unforeseen impact of changes in 
functionality, database, API, and the like *prior* to committing 
production data to the new version

* The user should be able to review release notes that clearly outline 
any deprecations, removals or significant changes in functionality, 
including API changes. These release notes ideally will indicate when a 
change has been made to the database schema.

* The user should have confidence that software vendor has tested the 
new versions against data loss, as well as unexpected regressions or 
changes in behavior. Further, that the vendor will any bugs or 
unexpected behavior should be addressed promptly.



As a consumer example, I never "expect" that if I upgrade an Android 
application that I'll be able to restore a previous version of the app 
and have it work with the database and other data from the newer version.



Personally, I'd rather more time go into the 3.x line utilizing the 
database backing store to improve performance, than having to make sure 
that "2.last" can somehow understand the new schema and revert it to XML 
or what have you.

My 2 cents, or pence, at the moment...

Jeff