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

I've added myself as a sponsor to this RFC and marked it as a draft. If anyone has any remaining comments on this proposal, please send them now.. http://wiki.php.net/pear/rfc/pear2_versioning_standard_revision On Mon, Jun 29, 2009 at 8:26 AM, Brett Bieber <brett.bieber@gmail.com> wrote: > On Sun, Jun 28, 2009 at 11:14 PM, Greg Beaver<greg@chiaraquartet.net> wrote: >> 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? > > This is *the best* thing! > >>> 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 would prefer to keep the initial API version flexible, by just > saying, a minimum of 0.1.0. > >>> 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. > > Agreed. > >> * 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 > > This sounds good, although I would prefer changing the initial api > version requirement to just be 0.1.0 at a minimum. > > Now, a simplified description: > Breaking backwards compatibility requires changing the major 'A' in > the A.P.I version. Once a package has been released as 'stable' the > changing the major 'A' in the A.P.I version requires changing the > major version 'X' in the X.Y.Z version in the package version. > >> How does that sound?  Clearer than the RFC? > > Sounds great. > >> Greg > > -- > Brett Bieber > -- Brett Bieber Office of University Communications University of Nebraska-Lincoln