Re: Suite of modules to be released - the name game
On 11/5/04 8:00 PM, Mark Stosberg wrote: > On Sat, Nov 06, 2004 at 12:29:23AM +, Smylers wrote: >> Nonetheless I feel it would be worth doing this for anything completely >> independent. It may be a little more hassle for you to release a few >> separate distros rather than one -- but it would be a lot more hassle >> for a potential user who just wants your DateTime or URI module to have >> to grab the entire suite. >> >> More to the point they are unlikely to be noticed as part of a suite, so >> your work won't get the attention and usage they deserve, and it's more >> likely that somebody else will repeat them (only slightly different, and >> incompatibly) elsewhere. > > I can second this. When I found Data::FormValidator, it was only > distributed as part of a larger framework...I didn't want the larger > framework, I just wanted the form validation. This module was not well > known at the time. Since Data::FormValidator has been released on it's > own, there's been a lot more activity around it. There are a few things that make this difficult. The first is that any OO "helper" module depends on the object base class and method maker. The second is that the object base class and method maker are very simple, and hardly worth distributing separately. The third is that even the functional helper classes are very simple, and usually only exist so that I have a single point of access for some functionality within my suite. For example, the DateTime utils consist of two important functions: parse_date() and format_date(). parse_date() parses the collection of date formats that I find it useful to parse. It does so the old-fashioned way, with a series of regexes in an elsif chain. It doesn't fit in at all with the DateTime::Format:: family, nor is it meant to. The format_date() function passes nearly everything through DateTime's strftime() method, but it adds one or two special formats, and changes the meaning of a few. The whole thing is a simple lib that just happens to accept and return DateTime objects. It exists so that, if I ever want to parse or produce a new kind of date within my modules, I can add code to one place. Now I can't imagine anyone else finding this utility class very useful unless they have exactly the same ideas as I do about what to parse and produce. Nor would any user of the overall suite be forced to use this class just because they use the suite. It's purely for internal purposes. The URI class might be vaguely useful to "the outside world", but it relies on the object base class and method maker. It also only handles a subset of the URI formats that URI handles (again, because that's all I need to handle internally). In both cases, what would these things be called? URI::Limited::ButEasyToManip? DateTime::Util::JohnsWhims? And then I'd have to tear out the object base class and method maker too: Object::Simple is probably already taken. The object base class is less than a page of code anyway. The method maker is a heavily simplified clone of Class::MethodMaker, which I deemed too heavyweight for the amount of functionality I use in it. But now my method maker exists only to hold all the weird kinds of methods that I find myself using within the suite. How many of those would be useful to others? The only part that absolutely will be useful outside the suite is the HTML objects module. But that depends on the object base class, the method maker, the URI class, and the DateTime util functions. So now I'm right back where I started, with everything in one big suite even if you just want the HTML objects. What I may consider is making the HTML objects and everything below them one suite, and then the web app stuff above it into another suite that depends on the HTML objects. But I'd still want them both under the branded namespace. It'd be two distributions, but one brand. So if you just wanted the HTML objects part, you could grab it while skipping the web app part. If I tried to put the HTML objects suite elsewhere in a non-branded namespace, then it'd seem odd that every web app object is a subclass of HTML::Objects::Object or wherever the supposedly generic HTML objects module suite lives. If I absolutely had to split things out as much as possible into bite-sized pieces (but all still branded), maybe it'd start to look like this (still using JCS:: in the example) JCS::Objects Includes JCS::Object, JCS::Object::MethodMaker::* JCS::DB::Objects Requires: JCS::Objects Includes: JCS::DB, JCS::DB::Object, JCS::Object::MethodMaker::DB::* JCS::HTML::Objects Requires: JCS::Objects Includes: JCS::DateTime::Util, and JCS::URI JCS::WebApp Requires: JCS::HTML::Objects (which in turn requires JCS::Objects) Includes: JCS::WebApp::*, JCS::WebSite::*, others (can't say what exactly because this part is the furthest from completion) Bundle::JCS Includes: all of the above Note that I stuck the db-related me
Re: Suite of modules to be released - the name game
On Sat, Nov 06, 2004 at 12:29:23AM +, Smylers wrote: > > Nonetheless I feel it would be worth doing this for anything completely > independent. It may be a little more hassle for you to release a few > separate distros rather than one -- but it would be a lot more hassle > for a potential user who just wants your DateTime or URI module to have > to grab the entire suite. > > More to the point they are unlikely to be noticed as part of a suite, so > your work won't get the attention and usage they deserve, and it's more > likely that somebody else will repeat them (only slightly different, and > incompatibly) elsewhere. I can second this. When I found Data::FormValidator, it was only distributed as part of a larger framework...I didn't want the larger framework, I just wanted the form validation. This module was not well known at the time. Since Data::FormValidator has been released on it's own, there's been a lot more activity around it. I've also released a project that sounds more like the scale of yours. The "small modules" I've released end up getting hacked on a lot more by others, who returns the improvements to me. So the extra effort to release bits separately has definitely paid off. Mark -- http://mark.stosberg.com/
Re: Suite of modules to be released - the name game
John Siracusa writes: > * A set of DateTime utility functions If these are generic DateTime utility functions, not tied into the rest of your suite, then they ought to be released as part of the DateTime namespace (or patched into existing modules in that namespace). But any name in that namespace should be approved by the DateTime mailing list. > Each component depends on some or all of the components above it in > the list. So while some components (e.g., the HTML objects) would be > useful in isolation, actually submitting them to CPAN outside of this > "suite hierarchy" is a bit of a hassle (for the users and the > developer) due to the dependencies. Nonetheless I feel it would be worth doing this for anything completely independent. It may be a little more hassle for you to release a few separate distros rather than one -- but it would be a lot more hassle for a potential user who just wants your DateTime or URI module to have to grab the entire suite. More to the point they are unlikely to be noticed as part of a suite, so your work won't get the attention and usage they deserve, and it's more likely that somebody else will repeat them (only slightly different, and incompatibly) elsewhere. Presumably your suite makes use of some Cpan modules that are maintained by people other than you? I think you should treat any generic 'helper' modules in the same way -- pretend to yourself that they weren't written especially for this project and treat them as Cpan dependencies. > It's my intention to release the entire suite as a "branded" entity > much like Mason, Maypole, or Bricolage, with a unique top-level > namespace to be determined later. (Obviously JCS:: will not do.) That's a good idea. Functional names work best for something like Image::Size or Math::Round -- something that solves a reasonably small and well-defined problem, and which people are likely to search for. But big 'Way of Life' suites probably spread best by word-of-mouth outside Cpan, and having a distinctive and memorable name works well. > but perhaps Mason ... ended up under HTML:: as some sort of > appeasement to the class hierarchy Gods. If so, this was a mistake, > and one I'd not like to repeat. I don't think it was a mistake, in that when I first heard the name HTML::Mason I could guess what the module does from the meanings of the separate words 'HTML' and 'Mason', something that isn't conveyed by just one of them. 'Bricolage' and 'Maypole' are different in that they are just brand names, and putting them in a namespace wouldn't help. > I suspect the guardians of naming are already poo-pooing my intention > to create a new top-level namespace for myself, ... The person who's done the most work in the past few years in helping people with naming is brian d foy on [EMAIL PROTECTED], and I've seen him actively encourage 'brand' names for large projects. Use a branded name for all the parts of your suite that are only useful in the suite. Use generic, meaningful names, for any parts that could be of use outside the suite. Then create a Bundle::WhateverYouCallYourSuite module that includes your suite plus its dependencies (other modules it uses that are in separate distros, whether published by you or other people). > * What should the branded name be? I already have a favorite picked, > but I'm open to guidance (e.g. "no copyrighted names", although I know > that one already :) Whatever you want! But try to pick something that is 'obviously' a branded name, and doesn't sound like it might be a meaningful name. So, for example, in the abstract 'CrossStitch' might work as a branded name. But putting that on Cpan clobbers that namespace from anybody who wants to release lots of modules for doing CrossStitch in Perl. > * Is it okay, or advisable to release a "partial" suite and then fill > in the rest of the components as they are completed? Yes. Release early and release often. That way you get more feedback, and it's easier to accommodate requests and suggestions. > * Is it okay to release modules before the documentation has been > completed? It's better to do it t'other way round -- release modules that have complete-ish docs but some of the documented things haven't been implemented yet! If something doesn't have docs, don't expect people to know what it's for or how to use it. I follow an RSS feed of Cpan uploads, and I investigate anything that sounds interesting. But if it doesn't have any docs then I don't ever bother downloading it just to see what it does. > * These are all version "0.01" at this point. Is that sufficient to > communicate the still-in-development nature of the suite, or should I > simply not release anything unless it's completely documented, at the > very least? I think at least outline docs would be a good idea -- giving the purpose and general idea of things. If that gets anybody interested then it isn't so bad if they have to read the source for the details. (Much
Suite of modules to be released - the name game
I have a big collection of modules that are currently under the JCS:: namespace (my initials). Together, they are meant to form a sort of web application construction kit. They're still under development, but I intend to release them to CPAN eventually. I'm also considering releasing parts of the suit as they get closer to completion. The modules are largely interdependent, although some subsets can exist in isolation. But all such subsets start from the lowest-level modules and go upwards in abstraction. Here are the major parts of the suite, roughly from the bottom up: * An object base class plus a simple method maker * A URI class * A set of DateTime utility functions * HTML objects (form objects) * A DBI wrapper * A library of SQL manipulation and generation functions * A db-backed object base class * A basic web application framework * An MVC-style web application base class First, a brief defense of a few of the things that seem like wheel reinvention: * A URI class - It actually uses the existing URI class, but stores the URI "in pieces" under the assumption that a URI will be manipulated many times, but serialized only once (or at least fewer times than it is manipulated). This usage pattern is true in my suite, thus the usefulness of the class. It also has some convenient URI manipulation methods that URI lacks. * A DBI wrapper / A db-backed object base class - Yes, there are already a bunch of these on CPAN...which means that, like me, each author wanted to do something, it not "better", then at least "differently" than any of his predecessors. TMTOWTDI! :) Moving on... Each component depends on some or all of the components above it in the list. So while some components (e.g., the HTML objects) would be useful in isolation, actually submitting them to CPAN outside of this "suite hierarchy" is a bit of a hassle (for the users and the developer) due to the dependencies. Let's look at two similar module suites already on CPAN: Mason and Maypole. Mason is actually HTML::Mason, of course, reflecting (I'd imagine) its creator's attempt to put it somewhere "logical" while not being too frivolous with the name: it assembles chunks of HTML like a mason building with bricks...or something. But not long after its introduction, it quickly became just "Mason" to developers. Furthermore, it also became clear that Mason is a lot more than just a way to assembles blocks of HTML. It is a more like a complete system for creating dynamic web sites and web applications. The HTML:: part of the class name, although well intentioned, is now just noise. Mason also includes things like its own method maker and various utility functions that could technically exist outside of Mason, but don't. Finally, there's the MasonX:: hierarchy which does away with the HTML:: baggage at last. Maypole is a more recent example. It's an MVC web application framework that avoids any pretense of being a "HTML builder" or any other sort of thing trying to find a home in an existing HTML::, Net::, Web::, HTTP::, or Apache:: namespace. It is essentially "branded." My suite is broader than either Mason or Maypole. In fact, it actually uses and depends on Mason (and possibly also Template Toolkit) as part of its web app framework. It's my intention to release the entire suite as a "branded" entity much like Mason, Maypole, or Bricolage, with a unique top-level namespace to be determined later. (Obviously JCS:: will not do.) I'm not sure if Maypole or Bricolage went through the module authors list, but perhaps Mason did, and ended up under HTML:: as some sort of appeasement to the class hierarchy Gods. If so, this was a mistake, and one I'd not like to repeat. I suspect the guardians of naming are already poo-pooing my intention to create a new top-level namespace for myself, but the sky did not fall when Maypole was introduced. Ditto for Alzabo, Rudesind, Bricolage, or even MasonX. Being nestled under Net:: or HTML:: or XML:: or whatever only makes sense for a certain class of modules. At some point, when the level of abstraction gets high enough, it's time to start assembling all of these reasonably nested, generic pieces into more complex "systems." Those systems will, by definition, not fit nicely into any part of the existing hierarchy. Trying to make them fit is disingenuous and leads to more confusion, not less. Someone looking for HTML manipulation modules will be quite surprised to run across a huge system like Mason sitting alongside things like HTML::Parser, for example. I think "branding" happens naturally for these suites simply because there are only so many generic names for "web application framework" or "templating system." I also think it's clear by now that branded names like AxKit, Mason, Maypole, or Bricolage are good fits for developer mindsets, even if they don't fit into the One True Taxonomy of CPAN (as if there is such a thing). As you can see, I'm pretty much sold on the "brande