API_STABILITY

This document is intended to detail Harbor's policy for releases and API
changes for official releases.

Please note, we need some more work defining what classes and methods make up
the public API -- in the meantime you'll have to use your best judgement (or
just ask us!).

Versioning Scheme
=================

Harbor releases will be versioned as follows: major.minor.maintenance. Major
releases, then, would be 1.0, 2.0, etc.; minor releases 1.1, 1.2; and
maintenance releases 1.0.1, 1.0.2.

API Stability
=============

Our goal is to change interfaces as infrequently as possible. We don't want to
rewrite our applications any more than you do.

Here are some details about the different releases.

MAINTENANCE RELEASES

Maintenance releases will be used for bug fixes and security updates. They will
always be compatible with their minor release.

If a bug or security hole is discovered, however, which requires a breaking
change, it will be applied to all relevant existing releases with a maintenance
release.

So, for example, if a particularly nasty bug is discovered in 1.1 and it also
effects 1.0.2, the patch will be applied and released as 1.1.1 and 1.0.3.

MINOR RELEASES

Minor releases will include new features, improvements for existing features,
etc. Existing features which will be removed or replaced will warn about
deprecation before being changed. Each minor release should be backwards-
compatible with its previous minor release, and code written for a minor
release should be forward-compatible with future minor releases with minor
changes.

  harbor-1.1 will be backwards-compatible with harbor-1.0. API changes will
    be flagged as deprecated.
  harbor-1.2 will be backwards-compatible with harbor-1.1, except in the case
    of deprecated methods.

MAJOR RELEASES

These may represent perhaps sweeping internal and external changes.