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

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: >>> >>> î3z„x+€9œ² >>> ·¨é×ó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