Salve J Nilsen wrote: >> For this reason I'd consider removing the concept of a seperate >> api_version entirely and just have "version" and "compatibility". I >> don't expect the two to drift far apart anyway. We tend not to track >> the progress of the API meticulously, too much manual work, but we do >> tend to realize when we break compatibility... or at least someone >> tells us. > > Something like this? > > --- > version: 1.33 > backwards_compatible_to: 0.99_02 > ---
Yes, something like that. >>>> stability: high >>> >>> Are you talking about the author's intentions here, or the module >>> history? >> >> We're talking about the author's opinion of this particular release. >> As mentioned elsewhere, borrowing Debian's "experimental", "unstable", >> "testing" and "stable" would be less subjective. > > Couldn't you just infer "stability" from comparing the package version > with the compatibility version number? It's a general indication of suitability for production use, both due to bugs and potentially ill thought out API features that might change. It answers the question "is it safe to install this?" It is necessarily subjective. A production server might want to stick with only "stable" releases while a development box can go with "unstable". CPAN Testers would want to go with at least "testing". Compatibility is also a "do I want to install this" concern, but a release which breaks backwards compatibility is not necessarily unstable. They are separate concerns and have separate resolution mechanisms. Since "stability" is ambiguous, you're not the first to point out the API vs bug stability issue, a better term should be found. Debian just says "distribution" and CPAN DSLIP refers to it as the "Development Stage". It might be worthwhile to look at the Debian and CPAN definitions for inspiration. http://www.us.debian.org/distrib/packages --------------------- stable: This is stable and well tested software, which changes only if major security or usability fixes are incorporated. testing: This area contains packages that are intended to become part of the next stable distribution. There are strict criteria a package in unstable (see below) must obey before it can be added to testing. unstable: This area contains the most recent packages in Debian. Once a package has met our criterion for stability and quality of packaging, it will be included in testing. unstable is also not supported by the security team. Packages in unstable are the least tested and may contain problems severe enough to affect the stability of your system. Only experienced users should consider using this distribution. ----------------------- Debian's aim is to provide a layered distribution aimed at moving releases through their testing system ultimately towards their stable distribution. Each release of a package stands on it's own. But Debian isn't in the business of developing code, just repackaging it. http://www.cpan.org/modules/00modlist.long.html#ID1_ModuleListi * i - Idea, listed to gain consensus or as a placeholder * c - under construction but pre-alpha (not yet released) * a/b - Alpha/Beta testing * R - Released * M - Mature (no rigorous definition) * S - Standard, supplied with Perl 5 DSLIP is more of a linear, historical progression and it applies to the package as a whole, not to the individual release. It has a bias towards one-way movement. The "idea" and "construction" stages are good descriptors of real world CPAN release cycles. There's a lot of incomplete modules on CPAN that are tossed up there in the "release early, release often" philosophy. DSLIP slices up "stable" into three separate categories which is, I think, a much finer grain than is necessary and too subjective for most use. Combining the best of the two, you wind up with something like... * incomplete Combining "idea", "under construction" and "experimental". This is not a complete work, but it's release to let others play with it. I prefer "incomplete" to "experimental" because it's a more concrete description of the state of the code. * unstable Might have bugs, features may change in incompatible ways. I prefer "unstable" to "development" because the latter can also describe "incomplete". It's also more useful in answering the question "should I use this release?" This would probably correspond to X.YY_ZZ alpha versions. * testing Works On My Machine, let's see what happens on others. * stable Suitable for production use. I think that covers the range of release quality at a pragmatic level of resolution to answer the question "should I use this release"? >>>> release_type: bugfix >>> >>> This may be useful, but doesn't this kind of info better fit into the >>> Changelog? (If you want it in a machine-parsable format, then I'd >>> look at Chris Dolan's Changelog.yml thoughts[1]. I like what he's >>> been doing.) >> >> Like I said to Eric, we don't control the Changelog format, but we do >> control META.yml. It will be difficult to get folks to change their >> change log format, but we control the META.yml. If you want META.yml >> to pull it's information from the change log that's fine, and it is a >> good idea, but when it comes to canonical release information let's >> try to keep it consolidated so installers only have to know about one >> file and format. > > What control are you talking about? Control by careful use of toolchain > defaults? By careful use of public examples and "Best Practices"? By > examples set in skeleton module helpers like Module::Starter and > ExtUtils::ModuleMaker? By peer-driven "sanity check regimes" like > Test::Kwalitee or Test::Perl::Critic? Right now, authors have complete control over the format of their change logs and have many and varied ways of generating them. If we suddenly try to enforce a change log standard, there's going to be a huge backlash and lots of people won't adopt it. That's assuming they're even AWARE of it. By contrast, META.yml has a clear specification and few authors have emotional attachment to the contents. It is almost always written by a handful of utilities (MakeMaker, Module::Build, Module::Install) which we control. Often authors aren't even aware to changes in META.yml, they simply come along with upgrading their installer. The change log thing is a good idea, in and of itself, but it requires individual author intervention and awareness and it's going to take a long time for it to be widely adopted. META.yml is so successful and wide-spread because it quietly builds itself from available information. >>>> api_version defaults to version. Since most folks don't religiously >>>> track when they add new things I believe this will be the normal >>>> state of affairs. >>> >>> So, the API would by default get it's version number bumped every >>> release? Would that give a correct impression about the state of the >>> package? >> >> It's a good guess. We tend to add subtle little new things in each >> release and few people meticulously define their API or document when >> each change was made. And most modules don't have to. > > Maybe so, but I think it would be useful to make the important changes > stand out some way. Adding new features to an API is easy, as you know; > changing and removing API features requires quite another level of > attention (Deprecation plans! Usage warnings! Screams of pain in the > documentation! Other nasty stuff!), and that's where a way to track API > compatibility really becomes useful. Going with an 80/20 mindset, I think that's all far more detail than I'd like to get into at the moment and can be added in later if necessary. Though I'm not sure if you're saying we should have a level of detail to handle all that (deprecation warnings about individual features, for example) or that we shouldn't... > I'm thinking that those "subtle little new things" are mostly covered by > proper use of the dependency metadata ("requires", "build_requires", > etc.) at the user's end, isn't it? I don't follow, can you elaborate? > If so, wouldn't it be sensible to use the API compatibility keyword(s) > just for the nasty stuff? -- You are wicked and wrong to have broken inside and peeked at the implementation and then relied upon it. -- tchrist in <[EMAIL PROTECTED]>
