Policy on backwards compatibility

[Norman Walsh <ndw@nwalsh.com>]

There was some disucssion of this a while back[1], but the action has
remained open on me to make an explicit proposal for a policy
statement for the TC to vote on. That statement is below.

In the discussion that followed when I first floated this proposal,
several people suggested that the "announced in the preceding version"
requirement was too strong; that it might lead to a point release
*just* to announce an incompatible change.

I agree that that situation could arise. However, I think it's
unlikely. Besides, I think it's very important that all DocBook users
know where such changes will be announced. Saying we'll announce it on
the email list or on the web site, isn't unreasonable but I expect
there are lots of users that don't pay any attention to either.

To my mind, the only thing we can be sure DocBook users will do is
download each release. Of course, there may be users that don't do
that either, but I can't think of anything that they're *more likely*
to look at than the release notes.

So I've left my proposal substantially unchanged. It's up to the TC to
decide if they share my concern.

My proposal for a backwards incompatible change policy:

The DocBook Technical Committee understands that the community
benefits from the long-term stability of the DocBook family of
schemas. We also understand that DocBook must continue to adapt and
change in order to remain relevant in a changing world.

All changes, and especially changes that are backwards incompatible
(changes that make a currently valid document no longer valid under a
new version of the schema), have a cost associated with them. Our duty
is to balance those costs against the need to remain responsive to the
community's desire to see DocBook grow to cover the new use cases that
inevitably arise in documentation.

With that in mind, the DocBook Technical Committee has adopted the
following policy on backwards incompatible changes. This policy spells
out when backwards incompatible changes can occur and how much notice
the TC must provide before adopting a schema that is backwards
incompatible with the current release.

This policy allows DocBook to continue to change and adapt while
simultaneously guaranteeing that existing users will have sufficient
advance notice to develop reasonable migration plans.

With respect to schema changes, the following points MUST always apply:

* A point release (X.1 to X.2, X.2 to X.3, X.1 to X.1.2, etc.) MUST
  NOT contain any backwards incompatible changes.

* A major release (X.1 to Y.0, X.2 to Y.0, X.1.2 to Y.0, etc.) MAY
  contain backwards incompatible changes if both of the following
  conditions are true:

  - The change was announced in the release notes for the previous 
    version (major or minor)

  - The change was announced in a release that occurred at least six
    months previously.

By these rules, the TC can announce, in V5.1 for example, its plans to
make a backwards incompatible change in V6.0. Then, in V6.0, if it's
been at least six months since V5.1 was released, it can make that
change.

                                        Be seeing you,
                                          norm

[1] http://lists.oasis-open.org/archives/docbook/200807/msg00029.html

-- 
Norman Walsh <ndw@nwalsh.com>      | Irrationally held truths may be
http://www.oasis-open.org/docbook/ | more harmful than reasoned
Chair, DocBook Technical Committee | errors.--T. H. Huxley

PGP signature