Author:         Jan Nijtmans <[email protected]>
State:          Draft
Type:           Project
Vote:           Pending
Created:        08-Dec-2015
Post-History:   
Tcl-Version:    8.7
Obsoleted-By:   595
Obsoleted-By:   599
Obsoleted-By:   628
Tcl-Branch:     semver

---

Abstract

The version schema used by Tcl and Tk has the form MAJOR.MINOR.PATCH, which is the same schema used by "Semantic Versioning" http://semver.org/ . For alpha and beta releases the schema is MAJOR.MINORaPATCH resp MAJOR.MINORbPATCH, which is not following the "Semantic Versioning" rules, but it's close. This TIP proposes to start using "Semantic Versioning" for Tcl and Tk, starting with Tcl/Tk 8.7, without making it mandatory for extensions and Tcl modules: existing extensions and modules written for Tcl/Tk 8.6 or lower must cooperate unmodified with later 8.x versions as well.

Rationale

Semantic Versioning is an attempt to assign meaning to a software version number. It has a very simple rule:

• Given a version number MAJOR.MINOR.PATCH, increment the:

  * MAJOR version when you make incompatible API changes,

  * MINOR version when you add functionality in a backwards-compatible manner, and

  * PATCH version when you make backwards-compatible bug fixes.

• Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

As the version number of Tcl has the same form MAJOR.MINOR.PATCH, nothing needs to be done here: future Tcl releases can be done following the Semantic Versioning rules. Tcl/Tk alpha/beta releases have the form MAJOR.MINOR[ab]PATCH, while Semantic Versioning dictates a form siminar to MAJOR.MINOR.0(-alpha.|-beta.)PATCH: numeric and non-numeric parts must be preceded by a dash, and separated by additional dots.

So, it is just a small step to adopt the Semantic Versioning idea. This TIP proposes to do just that, and describes the implications it has on Tcl and Tk. Alpha releases allow two forms of the version number, the semantic form MAJOR.MINOR.0-alpha.PATCH or the legacy form MAJOR.MINORaPATCH. For beta releases this will be MAJOR.MINOR.0-beta.PATCH resp MAJOR.MINORbPATCH. In Tcl 9.0, the legacy form might be removed and possibly enhanced to support all semantic versioning forms, but this is outside the scope of this TIP.

Semantic Versioning will only be adopted for Tcl 8.7 and higher, so Tcl 8.5.x and 8.6.x will not be affected. This means that it is possible to introduce a minor new feature in 8.6.6, which would mandate a MINOR increment under the Semantic Versioning rules. This TIP doesn't apply to Tcl extensions either, each extension writer is free in whatever version strategy they choose.

Proposed Change

This TIP proposes to adopt Semantic Versioning for Tcl and Tk 8.7 and higher. An exception will be made for Tcl extensions and Tcl modules, each extension and module author will be free to choose whether or not to adopt Semantic Versioning. Existing extensions/modules will continue to cooperate unchanged with future Tcl and Tk 8.x releases.

One of the implications of this change is that there - most likely - will be future Tcl 8.7/8.8/8.9/8.10 releases. Since all Tcl minor releases can be installed next to each other, this would be a maintenance burden since all of those versions need to be maintained during serveral years in the future. Solution: drop the minor number from all Tcl and Tk filenames and installation directories. This way, Tcl 8.7 and 8.8 cannot be installed next to each other any more, they share the same installation directory if the installation prefix is the same. Does that matter? No, because you always can choose a different prefix. Actually, there is no need for Tcl 8.7 any more when Tcl 8.8 is available, as they are 100% upwards compatible: the Semantic Versioning rules assure this. As soon as Tcl 8.8 is released, no new Tcl 8.7 releases will come out any more. Any incompatible change will have to wait for Tcl 9 (or 10 or 11...). Tcl 8.5 and 8.6 releases will continue to be supported as long as there is sufficient interest, this TIP doesn't change anything on that.

An important implication of dropping the minor number in the Tcl installation script directory is that it would become "/lib/tcl8" in stead of "/lib/tcl8.7". This is a problem, because this is the same directory used for Tcl Modules, which still need to support existing extensions. This TIP therefore proposes to change TCL_LIBRARY to '/share/tcl8', that won't conflict with anything used thus far.

Since Tcl now starts using TCL_LIBRARY being a subdirectory of "/share", it seems logical to start using this directory for man-pages as well. Therefore, it is proposed to upgrade "autoconf" to the latest version (2.69), which brings the man-page change without further hurdle.

All together, the proposed directory structure (UNIX)

/bin/tclsh8 Tcl executable

/lib/libtcl8.so Tcl shared library

/lib/tcl8 Tcl Modules

/lib/tcl8/8.6

/lib/tcl8/8.7

/lib/tcl8.6 TCL_LIBRARY for Tcl 8.6

/share/tcl8 TCL_LIBRARY for Tcl 8.x (x>=7)

/share/man Tcl manual pages

Regarding backporting, any change done in Tcl 8.7 could in principle be backported to Tcl 8.6 and further to 8.5, if desired. This TIP doesn't put a restriction to that, as Semantic Versioning only starts with version 8.7. Still it would be desirable for the TCT to describe a procedure for that, this is outside the scope of this TIP.

Semantic Versioning requires that any API which is removed in Tcl 9.0 must be made deprecated in some earlier minor Tcl 8.x release.

An implementation of this TIP can be found at https://core.tcl-lang.org/tcl ; branch "semver".

Rejected Alternatives

TODO

Copyright

This document has been placed in the public domain.