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

On Tue, 2009-12-29 at 14:11 -0600, Brett Bieber wrote: > 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 > I had a bunch of feedback prepared for this RFC but then today on IRC, Helgi, Brett and I uncovered a larger problem -- that of parallel installability. Here's the problem: * Package-A depends on the API of HTTP_Request 1.x * Package-B depends on the API of HTTP_Request 2.x * User Alice wants to use both Package A and Package B in her application. Under the proposed version standard, either Package-A can be installed, or Package-B can be installed, but both can't be installed at the same time. This is because the installed filenames and classnames could or would collide. In PEAR1(1) this was not a problem because developers were required to release a new package named HTTP_Request2 when a BC break was made. In PEAR(2), we could require all packages depending on API 1.x to update their use to be 2.x compatible before or during the 2.x API release. Then Alice could just upgrade Package-A at the same time as installing Package-B and both would use the 2.x API. In reality, package developers do not have time to track such API changes, and should not have to track changes if they are already depending on a stable 1.x API. So inevitably there will be packages depending on HTTP_Request 1.x, and packages depending on HTTP_Request 2.x. The RFC, as it stands, would restrict developers to developing against only a subset of PEAR. Alice has to choose either to only use packages compatible with HTTP_Request 1.x or packages only compatible with HTTP_Request 2.x. Since it is open-source, she also has the option of updating packages to use the 2.x API, but this is unreasonable to ask of end-user developers. Similarly, if Bob is a PEAR developer working on a new package, he has to decide to develop against HTTP_Request 1.x or 2.x. If more existing packages work with 1.x, maybe it makes sense for him to develop against 1.x so more people can use his new package. The adoption of HTTP_Request 2.x is hindered, and users and developers become fragmented. Considering those examples, it is imperative that the RFC allows both API versions to be installed and used in the same application. As discussed on IRC, there are two ways we can achieve this: 1. Adapt Pyrus to install packages in major-API-version-based sub-directories in the PEAR tree, and provide some programmatic way of switching the current API on-the-fly in code. For example, HTTP_Request would be installed in: PEAR/HTTP_Request-2.x/HTTP/Request.php PEAR/HTTP_Request-1.x/HTTP/Request.php The disadvantages here are this directory structure is unlikely to be popular, will cause problems for existing autoloader code, and will cause pain for developers who opt to use require_once statements. Additionally, I am not sure of either how we can switch API versions in code or how much extra complexity it would add for developers (both end-user and PEAR). Brett seemed to think switching API versions would be possible using namespaces, so perhaps he can share some ideas. 2. Do as we did for PEAR(1) and require the major version number to suffix the package name. I think this is the best solution as it is simple, and will "just-work" using existing standards (require_once, autoloaders, etc). It also does not require any extra programming to select the current API version. The second solution again removes the ability to have BC-breaking changes (major API bump) after a stable release of a package. With that ability gone, I do not see a need for the paranoia option; it would just add extra complexity. Unfortunately, I cannot vote in favour of this RFC as it stands. Regards, Mike > 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 >