Michael G Schwern said:
Salve J Nilsen wrote:
Michael G Schwern said:
http://use.perl.org/~schwern/journal/35127
What I would like is a way to explicitly indicate bug and API
stability, as well as compatibility, in META.yml. For example...
version: 2.01
api_version: 2.0
api_compatibility: 1.4
[snip about APIs]
What if there are several types in the same package?
You consider it from a user perspective. "Will it work?" is the
ultimate question. If I write code with version 1.3 and then upgrade to
2.1 will my code still work? Whether it be changes to the programmatic
interface, to the file format or a network protocol, if it breaks it's
not compatible. For example, if I write out Storable files with one
version will the new version read those files? This is *all* part of
the API. Perhaps a more comprehensive name than "API" is desirable.
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
---
Would it be sensible to introduce an API.yml file instead of
shoehorning stuff like this into the existing files?
META.yml is meant to be central, extensible clearing house of module
information, so there's no shoehorning necessary.
Hm. Yeah, if you're just talking about adding a "compatibility" keyword,
then I'm with you. I'd call it something less ambiguous, though. :)
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?
And how is this an improvement against established conventions with
version numbering? (0.x_99 vs. 1.0)
For one, X.YY_ZZ breaks simple numeric versioning and we need annoying
work arounds to make it work like $VERSION = eval $VERSION;
Or crazy stuff like this...
use version; our $VERSION = qv(0.1.1)->numify;
More importantly, because it can be explicitly stated rather than
guessed at. 1.0 means different things to different people. See this
for full discussion. http://use.perl.org/~schwern/journal/35127
I see your point. Version numbers by themselves don't say much at all
about stability, features or API changes. In fact, the verstion number is
close to useless without an up-to-date Changelog file.
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?
I think there are quite a few tools available to this community. Probably
more than enough for us to decide to create something "new" like a strict,
machine-readable version if the Changes file (e.g. "Changes.yml") and get
away with it.
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.
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?
If so, wouldn't it be sensible to use the API compatibility keyword(s)
just for the nasty stuff?
- Salve
--
#!/usr/bin/perl
sub AUTOLOAD{$AUTOLOAD=~/.*::(\d+)/;seek(DATA,$1,0);print# Salve Joshua Nilsen
getc DATA}$"="'};&{'";@_=unpack("C*",unpack("u*",':4@,$'.# <[EMAIL
PROTECTED]>
'2!--"5-(50P%$PL,!0X354UC-PP%/0\`'."\n"));eval "&{'@_'}"; __END__ is near! :)
