Versioning Policy

We have not yet decided upon a specific format versioning policy (other than, "We should have one."). Here are some of the questions that we need to answer:

  • What kind of change triggers a bump in the version number?
    • Adding a new tag?
    • Adding a new tag which is supported in the nbdoc component but not directly in nbshell (given, of course, that nbshell will fall back on displaying the raw XML).
  • Given a number-bumping change, exactly when do we bump the version number of the file format? Some options are
    • when the change gets checked in to SVN, and
    • when a new release of the tools is made.
  • What do our tools do when they encounter a file with an old version number?
    • Raise an exception?
    • Issue a warning and try to continue on?
    • Look up a registry of converters?
    • Raise an exception/issue a warning and tell the user to run a separate conversion tool or manually make the necessary changes (which may be only to bump the version number in the file).
  • Are we interested in any type of forward-compatibility? For example, if we support DocBook's bibliographic tags later on, they will still work in older versions of nbdoc and fail gracefully to raw XML in older versions of nbshell.
  • How do we deal with files that, for example, use DocBook tags that we don't directly support? Should such files be marked in the <head> metadata?
  • Do we attempt to do strict validation? Or perhaps the question should be, "how strict should our validation be?"

Decisions

  • Trac tickets that require bumping the version to complete should be labeled with the keyword version-bump.