[prev in list] [next in list] [prev in thread] [next in thread] 

List:       pear-dev
Subject:    Re: [PEAR-DEV] not-yet-draft RFC on the new versioning standards for
From:       Brett Bieber <brett.bieber () gmail ! com>
Date:       2009-06-29 14:26:08
Message-ID: efa010fb0906290726q2a48e5e1xcc1186d18358e49c () mail ! gmail ! com
[Download RAW message or body]

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

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php


[prev in list] [next in list] [prev in thread] [next in thread]