[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Policy on backwards compatibility
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]