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

On Wed, Jan 6, 2010 at 11:35 PM, Michael Gauthier <mike@silverorange.com> wrote: > > 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. Actually this has always been a problem for pre-stable packages, since API changes could be made at any time prior to the first stable release. > 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 This model is fairly common in unix/linux libraries, albeit with symlinks: /usr/local/lib/libxml2.2.6.32.dylib /usr/local/lib/libxml2.2.7.3.dylib /usr/local/lib/libxml2.2.dylib -> libxml2.2.7.3.dylib /usr/local/lib/libxml2.dylib -> libxml2.2.7.3.dylib > 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. Well, the include path can be modified programmatically so that regular require_once statements can be used. > 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. While we have uncovered potential issues once a package reaches a stable release, the paranoia option does improve the usability and safety of the upgrade process by allowing the end user to upgrade a package without the danger of BC breaking changes - this is important for pre-stable packages as well. I still am in favor of this change, as it defines what we're supposed to be doing with API versions, and it adds a level of security to the upgrade process, where there was none previously. The only change I would propose is in the POLICY, and to limit when developers change the major API version of a stable package. Keep in mind changing the API of a low-level library (such as HTTP_Request) is a major issue as there are so many packages that depend on it, but applications distributed as pear packages, and full-stack frameworks could greatly benefit from this RFC. Think ZF and ZF2 installable as PEAR packages. Same package name, different API. It is not likely that one end-user application would rely on an entire full-stack framework with two major API version differences, or that one application with two major api version differences would be installed on a single system and expect to talk to one another within the same code. There are exceptions to this, but this would likely be by people experienced with those applications — not the end-users that would blindly install and wonder why things were broken. Thanks for your comments and feedback Mike. > 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 > > > > -- Brett Bieber Office of University Communications University of Nebraska-Lincoln