Follow the Branching and Workflow of this guide.
x
+An important part of working with a +Distributed Version Control System (DVCS) like +fossil +is the management and use of branches.
+For Tcllib the main branch of the collection is +trunk. In git this branch would be called master, +and this exactly the case in the +github mirror of Tcllib.
+In support of debugging, like searching for when an issue +appeared via bisection, each commit on this branch must pass the +entire testsuite of the collection.
+As fossil has no mechanism to enfore this this is handled on +the honor system for developers and maintainers.
+To make the task easier Tcllib comes with a tool +("sak.tcl") providing a number of commands in support. These +commands are explained in the following sections of this guide.
+While it is possible and allowed to commit directly to trunk +remember the above regarding the testsuite, and the coming notes about +other possible issues with a commit.
+Because of this it is (strongly) recommended to perform any +development on a nicely named (nick of dev, ticket reference if any, +keywords applicable to the work, ...) non-trunk branch. Outside of the +trunk developers are allowed to commit intermediate broken states of +their work. Only at the end, when the branch is considered ready for +merging will it be necessary to perform full validation.
+In Tcllib all changes to a package have to come with an increment of +its version number. With what part is incremented (patchlevel, minor, +major version) dependent on the kind of change made. With multiple +changes in a commit the highest "wins".
+When working in a development branch the version change can be +defered until it is time to merge, and then has to cover all the +changes in the branch.
+Below a list of the kinds of changes and their association +version increments:
+No increment
No increment
Patchlevel
Patchlevel
Patchlevel
Minor
Major
Note, a commit containing a version increment has to mention +the kind of change which caused it in the commit message, as well as +the new version number.
+Note further that the version number of a package currently +exists in 3 places. An increment has to update all of them:
+The package implementation.
The package index ("pkgIndex.tcl")
The package documentation.
The "sak.tcl" command validate version helps +finding discrepancies between the first two. +All the other validate methods are also of interest to any +developer. Invoke it with
++ sak.tcl help validate ++
to see their documentation.
+The main directories in the Tcllib toplevel directory and of interest to a developer are:
Each child directory represents one or more packages. @@ -264,11 +340,11 @@
Each child directory "foo" contains one or more example application for the packages in "modules/foo". These examples are generally not polished enough to be considered for installation.
This directory contains files supporting the unix build system, i.e. "configure" and "Makefile.in".
This directory contains the sources of internal packages and utilities used in the implementation of the "installer.tcl" and "sak.tcl" scripts/tools.
????
The most common file types, by file extension, are:
Tcl code for a package, application, or example.
Tcllib developers invoke the suites through the test run method of the "sak.tcl" tool, with other methods of test providing management operations, for example setting a list of standard Tcl shells to use.
-Invoke either
./sak.tcl test run FOO
or
./sak.tcl test run modules/FOO
to invoke the testsuites found in a specific module "FOO".
Invoke the tool without a module name, i.e.
./sak.tcl test run
to invoke the testsuites of all modules.
In all the previous examples the test runner will write a combination of progress display and testsuite log to the standard output, showing for each module only the tests that passed or failed and how many of each in a summary at the end.
To get a detailed log, it is necessary to invoke the test @@ -401,11 +477,11 @@ short log.
Regardless of form, the detailed log contains a list of all test cases executed, which failed, and how they failed (expected versus actual results).
By default the test runner will use all the Tcl shells specified via test add to invoke the specified testsuites, if any. If no such are specified it will fall back to the Tcl shell used to ran the tool itself.
Use option --shell to explicitly specify the Tcl shell @@ -412,11 +488,11 @@ to use, like
./sak.tcl test run --shell /path/to/tclsh ...
Invoke the tool as
./sak.tcl help test
to see the detailed help for all methods of test, and the associated options.
Tcllib developers gain access to these through the doc method of the "sak.tcl" tool, another (internal) wrapper around the "modules/dptlite" application package.
-Invoke either
./sak.tcl doc html FOO
or
./sak.tcl doc html modules/FOO
to generate HTML for the documentation found in the module "FOO". @@ -440,26 +516,26 @@ Instead of html any other supported format can be used here, of course.
The generated formatted documentation will be placed into a directory "doc" in the current working directory.
Invoke the tool without a module name, i.e.
./sak.tcl doc html
to generate HTML for the documentation found in all modules. Instead of html any other supported format can be used here, of course.
The generated formatted documentation will be placed into a directory "doc" in the current working directory.
Invoke the tool as
./sak.tcl help doc
to see the entire set of supported output formats which can be generated.
Note the special format validate.
Using this value as the name of the format to generate forces the tool to simply check that the documentation is syntactically correct, without generating actual output.
Invoke it as either
@@ -566,19 +642,18 @@ reminder to put a check for this condition into the code.A last thing to consider when adding a new package to the collection is installation.
-How to use the tool, the "installer.tcl" script is -doumented in -Tcllib - The Installer's Guide.
-Here we document how to extend the installer so that it may -install the new package(s).
-In most cases only a single file has to be modified, +
How to use the "installer.tcl" script is documented +in Tcllib - The Installer's Guide.
+Here we document how to extend said installer so that it may +install new package(s) and/or application(s).
+In most cases only a single file has to be modified, the "support/installation/modules.tcl" holding one command per module and application to install.
-The commands are:
+The relevant commands are:
Install the packages of module name, found in "modules/name".
The code-action is responsible for installing the Index: idoc/man/files/devdoc/tcllib_devguide.n ================================================================== --- idoc/man/files/devdoc/tcllib_devguide.n +++ idoc/man/files/devdoc/tcllib_devguide.n @@ -379,11 +379,102 @@ .RE .IP [4] Follow the \fBBranching and Workflow\fR of this guide\&. .PP .SH "BRANCHING AND WORKFLOW" -x +.SS BRANCHES +An important part of working with a +\fIDistributed Version Control System\fR (\fIDVCS\fR) like +\fIfossil\fR [https://www\&.fossil-scm\&.org/] +is the management and use of branches\&. +.PP +For Tcllib the main branch of the collection is +\fItrunk\fR\&. In \fIgit\fR this branch would be called \fImaster\fR, +and this exactly the case in the +\fIgithub mirror\fR [https://github\&.com/tcltk/tcllib/] of Tcllib\&. +.PP +In support of debugging, like searching for when an issue +appeared via bisection, each commit on this branch must pass the +entire testsuite of the collection\&. +.PP +As fossil has no mechanism to enfore this this is handled on +the honor system for developers and maintainers\&. +.PP +To make the task easier Tcllib comes with a tool +("\fIsak\&.tcl\fR") providing a number of commands in support\&. These +commands are explained in the following sections of this guide\&. +.PP +While it is possible and allowed to commit directly to trunk +remember the above regarding the testsuite, and the coming notes about +other possible issues with a commit\&. +.PP +Because of this it is (strongly) recommended to perform any +development on a nicely named (nick of dev, ticket reference if any, +keywords applicable to the work, \&.\&.\&.) non-trunk branch\&. Outside of the +trunk developers are allowed to commit intermediate broken states of +their work\&. Only at the end, when the branch is considered ready for +merging will it be necessary to perform full validation\&. +.SS "VERSION NUMBERS" +In Tcllib all changes to a package have to come with an increment of +its version number\&. With what part is incremented (patchlevel, minor, +major version) dependent on the kind of change made\&. With multiple +changes in a commit the highest "wins"\&. +.PP +When working in a development branch the version change can be +defered until it is time to merge, and then has to cover all the +changes in the branch\&. +.PP +Below a list of the kinds of changes and their association +version increments: +.TP +\fID - documentation\fR +No increment +.TP +\fIT - testsuite\fR +No increment +.TP +\fIB - bugfix\fR +Patchlevel +.TP +\fII - implementation tweak\fR +Patchlevel +.TP +\fIP - performance tweak\fR +Patchlevel +.TP +\fIE - backward-compatible extension\fR +Minor +.TP +\fIAPI - incompatible change\fR +Major +.PP +.PP +Note, a commit containing a version increment has to mention +the kind of change which caused it in the commit message, as well as +the new version number\&. +.PP +Note further that the version number of a package currently +exists in 3 places\&. An increment has to update all of them: +.IP [1] +The package implementation\&. +.IP [2] +The package index ("\fIpkgIndex\&.tcl\fR") +.IP [3] +The package documentation\&. +.PP +.PP +The "\fIsak\&.tcl\fR" command \fBvalidate version\fR helps +finding discrepancies between the first two\&. +All the other \fBvalidate\fR methods are also of interest to any +developer\&. Invoke it with +.CS + + + sak\&.tcl help validate + +.CE +to see their documentation\&. .SH "STRUCTURAL OVERVIEW" .SS "MAIN DIRECTORIES" The main directories in the Tcllib toplevel directory and of interest to a developer are: .TP @@ -776,22 +867,21 @@ reminder to put a check for this condition into the code\&. .SH "INSTALLATION TOOLING" A last thing to consider when adding a new package to the collection is installation\&. .PP -How to \fIuse\fR the tool, the "\fIinstaller\&.tcl\fR" script is -doumented in -\fITcllib - The Installer's Guide\fR\&. -.PP -Here we document how to extend the installer so that it may -install the new package(s)\&. -.PP -In most cases only a single file has to be modified, +How to \fIuse\fR the "\fIinstaller\&.tcl\fR" script is documented +in \fITcllib - The Installer's Guide\fR\&. +.PP +Here we document how to extend said installer so that it may +install new package(s) and/or application(s)\&. +.PP +In most cases only a single file has to be modified, the "\fIsupport/installation/modules\&.tcl\fR" holding one command per module and application to install\&. .PP -The commands are: +The relevant commands are: .TP \fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR Install the packages of module \fIname\fR, found in "\fImodules/\fIname\fR\fR"\&. .sp Index: idoc/www/tcllib/files/devdoc/tcllib_devguide.html ================================================================== --- idoc/www/tcllib/files/devdoc/tcllib_devguide.html +++ idoc/www/tcllib/files/devdoc/tcllib_devguide.html @@ -119,34 +119,39 @@
-Follow the Branching and Workflow of this guide.
x
+An important part of working with a +Distributed Version Control System (DVCS) like +fossil +is the management and use of branches.
+For Tcllib the main branch of the collection is +trunk. In git this branch would be called master, +and this exactly the case in the +github mirror of Tcllib.
+In support of debugging, like searching for when an issue +appeared via bisection, each commit on this branch must pass the +entire testsuite of the collection.
+As fossil has no mechanism to enfore this this is handled on +the honor system for developers and maintainers.
+To make the task easier Tcllib comes with a tool +("sak.tcl") providing a number of commands in support. These +commands are explained in the following sections of this guide.
+While it is possible and allowed to commit directly to trunk +remember the above regarding the testsuite, and the coming notes about +other possible issues with a commit.
+Because of this it is (strongly) recommended to perform any +development on a nicely named (nick of dev, ticket reference if any, +keywords applicable to the work, ...) non-trunk branch. Outside of the +trunk developers are allowed to commit intermediate broken states of +their work. Only at the end, when the branch is considered ready for +merging will it be necessary to perform full validation.
+In Tcllib all changes to a package have to come with an increment of +its version number. With what part is incremented (patchlevel, minor, +major version) dependent on the kind of change made. With multiple +changes in a commit the highest "wins".
+When working in a development branch the version change can be +defered until it is time to merge, and then has to cover all the +changes in the branch.
+Below a list of the kinds of changes and their association +version increments:
+No increment
No increment
Patchlevel
Patchlevel
Patchlevel
Minor
Major
Note, a commit containing a version increment has to mention +the kind of change which caused it in the commit message, as well as +the new version number.
+Note further that the version number of a package currently +exists in 3 places. An increment has to update all of them:
+The package implementation.
The package index ("pkgIndex.tcl")
The package documentation.
The "sak.tcl" command validate version helps +finding discrepancies between the first two. +All the other validate methods are also of interest to any +developer. Invoke it with
++ sak.tcl help validate ++
to see their documentation.
+The main directories in the Tcllib toplevel directory and of interest to a developer are:
Each child directory represents one or more packages. @@ -271,11 +347,11 @@
Each child directory "foo" contains one or more example application for the packages in "modules/foo". These examples are generally not polished enough to be considered for installation.
This directory contains files supporting the unix build system, i.e. "configure" and "Makefile.in".
This directory contains the sources of internal packages and utilities used in the implementation of the "installer.tcl" and "sak.tcl" scripts/tools.
????
The most common file types, by file extension, are:
Tcl code for a package, application, or example.
Tcllib developers invoke the suites through the test run method of the "sak.tcl" tool, with other methods of test providing management operations, for example setting a list of standard Tcl shells to use.
-Invoke either
./sak.tcl test run FOO
or
./sak.tcl test run modules/FOO
to invoke the testsuites found in a specific module "FOO".
Invoke the tool without a module name, i.e.
./sak.tcl test run
to invoke the testsuites of all modules.
In all the previous examples the test runner will write a combination of progress display and testsuite log to the standard output, showing for each module only the tests that passed or failed and how many of each in a summary at the end.
To get a detailed log, it is necessary to invoke the test @@ -408,11 +484,11 @@ short log.
Regardless of form, the detailed log contains a list of all test cases executed, which failed, and how they failed (expected versus actual results).
By default the test runner will use all the Tcl shells specified via test add to invoke the specified testsuites, if any. If no such are specified it will fall back to the Tcl shell used to ran the tool itself.
Use option --shell to explicitly specify the Tcl shell @@ -419,11 +495,11 @@ to use, like
./sak.tcl test run --shell /path/to/tclsh ...
Invoke the tool as
./sak.tcl help test
to see the detailed help for all methods of test, and the associated options.
Tcllib developers gain access to these through the doc method of the "sak.tcl" tool, another (internal) wrapper around the "modules/dptlite" application package.
-Invoke either
./sak.tcl doc html FOO
or
./sak.tcl doc html modules/FOO
to generate HTML for the documentation found in the module "FOO". @@ -447,26 +523,26 @@ Instead of html any other supported format can be used here, of course.
The generated formatted documentation will be placed into a directory "doc" in the current working directory.
Invoke the tool without a module name, i.e.
./sak.tcl doc html
to generate HTML for the documentation found in all modules. Instead of html any other supported format can be used here, of course.
The generated formatted documentation will be placed into a directory "doc" in the current working directory.
Invoke the tool as
./sak.tcl help doc
to see the entire set of supported output formats which can be generated.
Note the special format validate.
Using this value as the name of the format to generate forces the tool to simply check that the documentation is syntactically correct, without generating actual output.
Invoke it as either
@@ -573,19 +649,18 @@ reminder to put a check for this condition into the code.A last thing to consider when adding a new package to the collection is installation.
-How to use the tool, the "installer.tcl" script is -doumented in -Tcllib - The Installer's Guide.
-Here we document how to extend the installer so that it may -install the new package(s).
-In most cases only a single file has to be modified, +
How to use the "installer.tcl" script is documented +in Tcllib - The Installer's Guide.
+Here we document how to extend said installer so that it may +install new package(s) and/or application(s).
+In most cases only a single file has to be modified, the "support/installation/modules.tcl" holding one command per module and application to install.
-The commands are:
+The relevant commands are:
Install the packages of module name, found in "modules/name".
The code-action is responsible for installing the