On Jun 30, 2014, at 7:43 PM, Andrew Phillips <aphill...@qrmedia.com> wrote:
>> 2. Deprecation of code and removal of deprecated code will only happen on >> major releases (e.g. MAJOR.0) > > Whilst I can see how this might be easier for us to formulate as a rule, this > would mean that it might take *two* major releases before we can effectively > get rid of something, if I understand the proposal correctly? E.g. if we've > just released 2.0.0 (i.e. master is at 3.0.0-SNAPSHOT) and we want to > deprecate something, the deprecation has to wait until 3.0.0 and the removal > happens in 4.0.0. > > If we're still planning on releasing majors roughly every 6-9 months, this > would mean a waiting period of over a year. That seems a little long to me? > Obviously, if we allow deprecation in a minor version, we shouldn't deprecate > it in the minor version right before a major release and then immediately rip > out the code. But I think we can avoid that, and can also formulate that in > the guide if necessary. You’ve understood my proposal correctly. Breaking client code (aka deprecation) is something that should be properly planned. If it hasn’t been properly planned then you could easily get into the situation you’ve described and that’s okay in my opinion. If it hasn’t been properly planned then it probably should wait longer. Some projects never break client code. I think that’s one extreme that won’t serve us or our users well. To ease any pain associated with breaking code, we do need to make it very predictable. And making breaking changes at major release boundaries only achieves that goal. >> A concern about the jclouds-labs section [3]. By having that in there, I >> guarantee you users will extrapolate and apply that to *all* labs repos >> whether we like it or not. > > Fair point. I can see two immediate alternatives: renaming the other labs > repos to remove the word "labs" (perhaps too painful), or going through and > adding @Beta to all providers and APIs in labs (more accurate because then we > just have to define what @Beta means). The renaming/moving repos is a whole other discussion. ;) Frankly, I don’t know what to do here. Remove the section or keep it. If you want to keep this section, could you please start it out with “This applies to jclouds-lab and jclouds-labs only”? I really don’t want us to get too distracted by this subject. >> The old methods, classes etc. can be removed from master in the next major >> release > > So that would mean they stay around on master too until the next major > release is cut (i.e. the last round of commits would be a bunch of removals > of deprecated stuff). Is there any specific reason not to remove them from > master - which to me represents "the bleeding edge", i.e. the current state > of the project - immediately? The reason I'd prefer this, if possible, is > that we can at least try to treat master as "free of cruft that we are about > to remove”. I see what you mean but wouldn’t that make backporting very difficult if not impossible in some situations? > To your other question: > > "jclouds aims to not promote a method or class out of beta - or to discard it > - by the major release ''after'' next (i.e. A.D.0 if the current release > branch is A.B.x). < I'm confused by this. I'm not sure what the intent is > here. Could this be replaced by..." > > The intent was to somehow clarify to users that we don't intend to declare > APIs or providers as @Beta and then leave them in that state forever. I was > wondering if it would make sense to try to codify for ourselves, and our > users, that @Beta indeed indicates a limited trial period with a clear > "go/no-go" decision after a specific amount of time. I understand now. What did you think of this alternative wording? "Beta methods and classes will be promoted to non-beta status or removed only in major releases (e.g. MAJOR.0)" Thanks, Everett
