Feature Proposals » Create a new root-level namespace for developer modules and tools

Motivation

Right now I am trying to have an easy, fast and automated way to build PortableTWiki. Building A Release is neither easy nor fast, and only partially automated. Some scripts seem to rely on command line tools not reliably available on Windows, but the "personal" executable for Windows must be built on Windows.

So I try to write portable perl code to glue it all together, but I don't find a good place for it. In particular, I'd prefer to to create an up-to-date testable distribution without going through the tedious SVN checkout processes, but instead just collecting stuff from all the MANIFEST files.

Description and Documentation

The TWiki SVN tree mixes distribution stuff with developer stuff in a way which is sometimes confusing and sometimes cumbersome. Confusing because different developer tools are in different directories, not very consistent with regard to parameters and documentation, and it is not always clear whether they want to be started from the SVN root or from the core directory; and cumbersome because of the convoluted namespace conventions. Plugins.BuildContrib is a starter, but as soon as you start to build object hierarchies for the build process, you'll end up with TWiki::Contrib::BuildContrib::Manifest::Item which eats half of a decent source code line where it could be as short as TWikiDev::Manifest::Item.

I am fine with having the stuff in a contrib with regard to SVN directory structure, either a new one or by extending BuildContrib. But I'd like to have one directory with developer scripts, and one namespace for developer modules. If it is in a contrib, I'd still prefer to add its lib directory to @INC and its tools (or bin, or script, however we call it) to $PATH, and avoid having to pseudo-install the contrib. Developer tools are likely to have a different development cycle than TWiki itself, so it would be irrelevant whether my current directory is branches/TWikiRelease06x00 or trunk.

An alternative to writing TWiki developer modules would be to drop MANIFEST and BuildContrib, and to switch to standard Perl ecosystems like CPAN:Dist::Zillla, CPAN:prove. But this is a second step. Or a third step.

Examples

• For running tests, I have to cd test/unit and then to run perl ../bin/TestRunner.pl TWikiSuite.pm. Ugly. Instead, I'd prefer to have one command in my $PATH, and from wherever the current directory is, say twikidev test /path/to/TWikiSuite.pm.
• For creating a new extension, BuildContrib recommends perl create_new_extension.pl. The script is in the core directory, but extensions need to be created in SVN root, so after creating the extension I need to move it upwards. Ugly. I'd rather write twikidev new_extension [extension_name] and have it do the right thing.
• There is already the Unit namespace, occupied by unit tests. This is better than TWiki::Contrib::UnitTestContrib::Unit. Still better, IMHO, would be TWikiDev::Unit, because it makes clear that this is developer stuff which never needs to be distributed, unlike the other root-level modules Assert.pm and Monitor.pm.
• PTh has scripts to copy stuff from trunk to branches/TWikiRelease06x00 and vice versa, and I happen to have similar tools. If there's a dedicated place for such tools, they could go into trunk SVN.

Impact

This is not a matter of writing code right now, but rather a matter for a new convention, which asks for discussion at a release meeting.

Implementation

-- Contributors: Harald Jörg - 2015-05-17

Discussion

I've made a start, for my very own purposes, and submitted to SVN:

• twikidev collect - collect files from one or more MANIFEST files to a separate directory, correctly merging directories from core with extensions (to be run from a SVN checkout area). This is an incredibly fast initial step for BuildingARelease from SVN Head.
• twikidev packtwp - starting with a collection created by the above subcommand with a MANIFEST created for this very purpose, build TWiki Personal for Windows (to be run on Windows).
• twikidev t2b - copy file(s) from trunk to branch.

The framework provides for free:

• twikidev - without subcommands, list available commands
• twikidev help [subcommand] or twikidev [subcommand] --help - describe parameters of [subcommand]

I've waaay more ideas for more stuff than time at hand

-- Harald Jörg - 2015-06-03