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 > > Which API? Are we only talking about the programming interface, or are > we also considering protocol and storage file format versions/changes?
Yes, all that. :) > How would you distinguish between these? You don't have to. :) > 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. > 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. >> 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. > 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; 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 >> 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. Also, I don't like to combine two experiments together. They tend to produce problems much greater than the sum of their parts. >> 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. >> stability defaults to high > > How optimistic :-P Yes, and it's what we assume right now. META.yml generators are free to support existing conventions by filling in a missing stability/release based on an X.YY_ZZ version. -- Life is like a sewer - what you get out of it depends on what you put into it. - Tom Lehrer
