On Jul 2, 2014, at 4:14 PM, Andrew Gaul <g...@apache.org> wrote: > Giving a date-based notice as Guava does for some recent breakages, > e.g., InputSupplier scheduled for removal in December 2015, makes some > amount of sense given jclouds historical lack of major release > predictability. However, I generally doubt that we can provide strong > guarantees about breakages while addressing the large backlog of jclouds > technical debt and relying on Guava deprecated and beta APIs.
Because we’ll have both a major and minor release cadence the release dates will be predictable. Of course things will drift a bit because of holidays or voted down RCs but it will still be predictable. Saying something is going to be removed in version X is akin to saying something will be removed on date X. > Further I do not understand the proposed workflow for changing or > removing an API. Let's assume we are at 1.7.3 as today and will release > 1.8.0 in a month, and new major versions every six months. At which > point in the development cycle can I commit a breaking change to master: > > 1) at any point before 1.8.0 release > 2) immediately after 1.8.0 release > 3) at any time during 1.8.x > 4) when someone changes the project version to 2.0.0 > > Previously we allowed 1-4 but the proposed scheme only allows for 4? > When do we decide to bump the major version number and which fraction of > the release cycle allows breaking changes? On an example 6 month major release cadence 3.0 3.1 - 6 weeks 3.2 - 6 weeks 3.3 - 6 weeks 4.0 Pre 3.0 you have class Foo you want to replace with class Bar. Anytime prior to 3.0 you can make commit (a) to master that adds class Bar and deprecates Foo which includes the annotation to use Bar and the fact that Foo will be removed in 4.0. Commit (a) should not be backported. Anytime after 3.0 you can make a commit (b) to master that deletes class Foo. Commit (b) should not be backported. That’s it. To me that’s simple and predictable. It always gives users 6 months to deal with breaking changes and backwards incompatible removals only happen in major versions. Yes we could open it up to say you can deprecate and remove things outside of major release boundaries as long as you give users 6 months notice (e.g. 3.2 to 4.2 as above) but that seems complicated and counter-intuitive to users. > Also consider a more complicated example, I tried to accommodate the > most number callers when moving from InputSupplier to ByteSource but > strongly suspect that I caused breakages for several users and I still > have not completed this work. How would we address this under the > proposed scheme, given that Payload *implements* the deprecated > InputSupplier interface, other than introducing a new Payload2 class. I don’t think we should optimize around a particularly tangled example. There can always be exceptions to the policy or guidelines or whatever it is we’re talking about here though. > This discussion discourages me since it discusses some idealized > breakage policy and does not connect to the reality of where jclouds > exists. Going forward this semantic versioning discipline and ongoing > API changes will ensure that we bump the major release number > (MAJOR.y.z) every time instead of the minor one (x.MINOR.z) I’m not sure where this comes from. The major and minor release cadence would remain the major and minor release cadence. We wouldn’t bump the major release arbitrarily because we felt like making breaking changes. We would bump it in line with the major release cadence ensuring our users have at minimum 6 months to deal with breaking changes. There’s no point in having a cadence if we don’t follow it. > but this > does not really do anything for users except for moving a number around. > Strong promises of compatibility will discourage many (breaking) > improvements, big and small. I worry about this a lot given the > existing quirky jclouds API and the large about of suboptimal API use I > observe in Stack Overflow questions and jclouds-user mails. Are you working under the idealized assumption that users are tracking jclouds code very closely and are consuming breaking changes rapidly? I can guarantee you this is not the case. So many old versions are still in use. Not having a predictable deprecation policy guarantees that users will be more likely to stay marooned on old versions because they’ll have no idea at what point things will break on them. I think making potentially breaking changes every 6 months is actually very progressive in the world of Java. I think it’s a good trade off between providing a stable and predictable platform for users to build the businesses upon vs improving that platform in backwards incompatible ways. Regards, Everett
