Re: not-yet-draft RFC on the new versioning standards for PEAR2 (needs PEAR Group sponsor to be official)

Brett Bieber wrote: > On Sat, Jun 27, 2009 at 11:51 AM, Greg Beaver<greg@chiaraquartet.net> wrote: > >> I've summarized the changes that could happen at this RFC address. Feel >> free to pick it apart - this needs to be rock-solid and clear. Once it >> seems to have settled, I'll seek a PEAR Group sponsor so they can take >> it up. >> Here is the RFC incomplete draft: >> >> >> http://wiki.php.net/pear/rfc/pear2_versioning_standard_revision >> > > This is something that came to mind regarding stability attributes... > forgive me if they're incomplete thoughts. > I absolve you as the patron saint of incomplete thoughts. > What purpose do the api and version stability attributes serve under > this versioning RFC? > > If we adopt warnings regarding api version changes, then there is less > risk installing a "beta" package, as you'll be warned if the api > changes when you attempt an upgrade. > Although this was not the intention, mitigating risk isn't so bad, so this is a good thing, right? > Somewhat related - requiring 1.0.0 = stable. > Under this proposed versioning standard, the developer releases 0.2.0, > everything went great and would like to go stable. The API does not > change as everything is perfect, but the developer is required to > change the API version to 1.0.0 when he goes stable. Will this NOT > upgrade with the default paranoia level because it is x+1? > going from 0 to 1 is a special case, isn't it. Perhaps we should require the initial API to be 1.0.0a1 instead of 0.1.0? I'll make that change. This way, you can bump to 2.0.0 as needed, and if you don't, no BC break warning when releasing the stable release. > I understand the purpose of allowing development and major changes > prior to a 1.0.0 release, but, if the package developer follows the > instructions regarding api changes — and the installer will warn the > user when the api changes according to their paranoia settings — why > require them to use specific x numbering when a release reaches > stable? > To be clear - I assume you are talking about specific *release* X version numbering, as opposed to specific *API* X version numbering? The intention is to relax versioning requirements so that release version 2.0.0 can be released, something PEAR prevents. It also relaxes the definition of what 2.0.0 is. 2.0.0 can be used for a major non-BC breaking feature addition at the developer's discretion. > Alternatively, the package hasn't reached stable yet, but I wanna > break BC for all my alpha/devel/beta releases because I've got a > better api design idea. So I want to use x+1 so that people following > the development don't upgrade and break their code. Can I not do this? All good points, I love this kind of feedback. I've written and erased this email a few times, which I think is a good indicator of how dangerously close to over-complex this can get. We need two sets of rules on versioning: one for initial development, and one for post-1.0.0. * Pre-1.0.0, the rules should be: For version X.Y.Z and API version A.P.I 1) First release is 0.1.0/alpha or devel, API 1.0.0a1 alpha 2) First release candidate is 1.0.0RC1/beta, API A.P.I/stable 3) increment Y and P if features added, or API changed, set Z=I=0 4) increment Z and I if any API bugs fixed 5) increment Z if bugs fixed * Post-1.0.0, the rules should be: 1) 1.0.0 has a stable A.P.I 2) all releases with BC breaks, X.Y.Z = (X+1).0.0, A.P.I = (A+1).0.0 then goto rule 7 3) all releases with major feature additions (developer discretion), X.Y.Z = (X+1).0.0, A.P.I = A.(P+1).0 then goto rule 7 4) all releases with minor feature additions (developer discretion), X.Y.Z = X.(Y+1).0, A.P.I = A.(P+1).0 then goto rule 7 5) all releases with API bugfixes, X.Y.Z = X.Y.(Z+1), A.P.I = A.P.(I+1) exit 6) all releases with just bugfixes X.Y.Z = X.Y.(Z+1), A.P.I. = A.P.I exit 7) use X.Y.Za1 for first alpha release, X.Y.Zb1 for first beta release, X.Y.ZRC1 for first release candidate All releases should follow these rules: 1) API stability can never be less stable than the release stability, but release stability can be less stable than API stability How does that sound? Clearer than the RFC? Greg