James, JW> I see [API breaking changes hanging out on a feature branch where other changes might in turn break them] as being a risk and a maintenance hassle
Yes. *Breaking APIs inflicts hassle* at least one way or another. Either these breaking API changes are increasing the cost of non-API-breaking-changes, or non-API-breaking changes are potentially increasing the cost of eventually merging the API-breaking changes. *Moving API breaking changes into feature branches moves that hassle away from the center of the stage.* JW> I like master having the latest of everything integrated into it. Sure. But I like master having *the latest **non-API-breaking** code*, since that's what I most care about for MyUW. It's also what I expect a *typical adopter* and a typical new adopter to be most interested in working from. So long as the project is doing Major releases regularly (and so API-breaking changes do make it into Master, it's just they do so only every 18 months or so), *hanging out on the non-API-breaking changes off of the latest Minor release is going to be adequate to most adopters' needs, the right place on the stability-features tradeoff curve.* It's a matter of being less casual about breaking APIs. There'd be nothing to stop a next_version branch representing the combination of those API-breaking feature branches, so as to combine their maintenance, if there's a real efficiency to be had there. However. I suspect that in practice this is less of a problem than one might think: While `master` is marching towards the next Minor release **APIs are not being broken** and so those *changes on `master` should not break the API-breaking features that are hanging out on feature branches.* So it should normally true that *API-breaking Feature branches continue to merge cleanly onto master* for the up to 18 months before it's time to merge them to master and cut another Major release. If they don't,* it's better to have that hassle in the feature branch that is about making an API-breaking change than it is to have that hassle dragging on non-API-breaking enhancements to the current released uPortal.* To the extent that there are multiple proposals to break APIs in different, non-compatible ways, well, that's certainly a problem that will need hashed out and resolved. We could detect that sooner with a `next_version` branch representing the union of these API breaking changes slated for the next release, but I suspect that deferring dealing with that until when we try to merge it all together for the next Major release would be fine in practice too. JW> adopters having to pick and choose feature branches Eh. To the extent that these API-breaking-changes are so compelling that they're being adopted in production by multiple adopters and that their maintenance is a problem, that's evidence that it's time to cut that Major release and ship those changes and embrace, well, really maintaining that product. *I think we should optimize for adopters adopting released code, not for adopters adopting un-released code.* I don't see adopters having to grab these API-breaking feature branches so very often. They can not do that and *pick them up at the next regular Major release.* Or we could get to good enough APIs such that the compelling features that adopters want can be implemented in changesets that don't break APIs, even external projects written to stable APIs. * If uPortal aspires to be a Platform, then it needs to have APIs that are good enough that they can cruise for 18 months without urgently needing breaking. *Having stable APIs to which one can write compelling things is part of what makes something a platform. JW> If we are truly doing something toward 'moving the decimal', then master should remain the latest and greatest of all accepted changes and we selectively back-port feature additions into the rel-4-x-patches like we used to with the 4.0.x line and periodically release minor versions. Sure. Supposing uPortal adopts semantic versioning for a uPortal 5.0.0 release (cleanest example), could go with * 5.0-patches : Bugfixes (that don't break APIs) on uPortal 5.0.0. Cuts 5.0.1, 5.0.2, 5.0.3... * 5-patches : Non-API-breaking enhancements on uPortal 5.0.0. Cuts 5.1, 5.2, 5.3, ... . Includes bugfixes from 5.0-patches. * master : API breaking changes marching towards uPortal 6.0.0; Includes bugfixes from 5-patches. I don't see this as ideal for a couple reasons. One is that it makes API breaking changes central and the norm by using `master` for this. Another is that it guarantees maximum tedious effort in the shared burden of keeping master up-to-date. If I make a backwards-compatible change adding value to 5-patches, I suppose I'm supposed to also go figure out how to apply that change to `master` where the involved APIs may have changed. Sounds like friction in making a backwards-compatible change providing value to current adopters now. I'd prefer something more like this upon a uPortal 5 release adopting Semantic Versioning: * 5.0-patches : Bugfixes (that don't break APIs) on uPortal 5.0.0. Cuts 5.0.1, 5.0.2, 5.0.3. Very conservative adopters might track this. * master : Non-API-breaking enhancements on uPortal 5.0.0. Cuts 5.1, 5.2, 5.3, ... . Includes bugfixes from 5.0-patches. Typical adopters will track this. This is the center of the project, the thing we are collaborating upon and regularly adopting. Various feature branches where API-breaking changes hang out. For example, say * spring4 : adopts latest Spring Framework! * spring_security_4_reals : deletes uPortal-specific security code in favor of just using Spring security * liquibase : adopts liquibase for database schema versioning * no_commons_logging : excises every inferior commons logging usage in favor of erudite slf4j usage etc. Under this approach, if I make a backwards-compatible change adding value to master, I don't worry much about whether and how that might break feature branches that represent un-released code proposed for inclusion in the next major release. If it's caught earlier, great, might be interesting to think about -- but if that pain is deferred to the next Major release, no great loss. *I don't expect most adopters to be sufficiently interested in those API-breaking features to want to take on the hassle of locally adopting those changesets,* and that's fine. They hang out in public feature branches under review and collaboration and discussion on up-dev@. We collaborate on composing, perhaps most importantly, the API-breaking-changes that are most worthwhile for getting to APIs such that we less need to break those APIs to do great things in the uPortal 6 release series. Whenever it feels right in 18 months or so, master becomes about cutting uPortal 6 rather than another uPortal 5.x minor release, and at that point, for each feature branch, *either the feature is worth rebasing / merging / figuring out how to get it to apply to master for the Major release, or it isn't.* There's some pain, but it's deferred pain to the point where that pain is valuable and when we know what we need to know for what it looks like to include the features in uPortal 6, what the APIs are in uPortal 6. Merge the feature branches, get stable, cut an RC, cut a 6.0 release, and then uPortal 6 becomes the center of the uPortal project, marching along in master with non-API-breaking enhancements taking advantage of those APIs ... until pressure has accumulated to go after a uPortal 7. *All that said, if we're not ready to move the culture* on what master is and having * 5.0-patches : Bugfixes (that don't break APIs) on uPortal 5.0.0. Cuts 5.0.1, 5.0.2, 5.0.3... * 5-patches : Non-API-breaking enhancements on uPortal 5.0.0. Cuts 5.1, 5.2, 5.3, ... . Includes bugfixes from 5.0-patches. * master : API breaking changes marching towards uPortal 6.0.0; Includes bugfixes from 5-patches. is *what allows uPortal to adopt Semantic Versioning, I for one would be willing to make that compromise.* Improve the versioning, and then circle back and improve everything else that's facilitated by improved versioning. :) Kind regards, Andrew On Thu, Sep 18, 2014 at 12:37 PM, James Wennmacher <[email protected]> wrote: > I finally had a chance to quickly review the write up. Nice job on the > write up. I'm all for semantic versioning as a concept, and I think > releasing 4.2.0, 4.3.0, etc. on a fairly frequent, regular basis > (quarterly seems fine) makes quite a bit of sense. > > Perhaps I misunderstand, but I did have some concerns about having > api-breaking changes hanging out in feature branches for large periods of > time (up to 18 months per suggested schedule) because I see that as being a > risk and a maintenance hassle. It runs the risk of those feature branches > becoming stale and adopters having to pick and choose feature branches. I > like master having the latest of everything integrated into it. If we are > truly doing something toward 'moving the decimal', then master should > remain the latest and greatest of all accepted changes and we selectively > back-port feature additions into the rel-4-x-patches like we used to with > the 4.0.x line and periodically release minor versions. > > Let me know if I misunderstood. > > Thanks, > > James Wennmacher - Unicon > 480.558.2420 > > On 09/08/2014 12:55 PM, Andrew Petro wrote: > >> uPortal developers, >> >> I鉅 gotten some off-list concern about the wisdom of adopting Semantic >> Versioning in uPortal. In the course of thinking through that, I靶e had >> >> occasion to re-articulate why uPortal ought to adopt Semantic Versioning. >> >> http://apetro.ghost.io/uportal-should-semver/ >> >> >> I remain convinced this is the right move for uPortal. >> >> >> Andrew >> >> >> >> On 6/19/14, 12:48 PM, "Andrew Petro" <[email protected]> wrote: >> >> Aaron, >>> >>> I'm glad to hear this is resonating with you! >>> >>> I think you're right, that the meaning of uPortal product version >>> numbers would be more readily apparent under Semantic Versioning and >>> that this will help as uPortal products evolve to better define APIs. >>> >>> I didn't emphasize in my initial writeup, but would if I had to do it >>> over again, this advantage: reducing the need to apply new features to >>> multiple development branches. Git helps, but it's still a drag to, for >>> each feature, consider whether it goes into just master or into master >>> and 4.0-patches, and if it goes in both, to track that to completion and >>> adjust to meld appropriately with the differences between those >>> branches, and... I think it'll be healthier to only be dealing with >>> applying changes to multiple branches when they're pointed bugfixes. >>> >>> Kind regards, >>> >>> Andrew >>> >>> >>> On 6/19/14, 10:22 AM, Aaron Grant wrote: >>> >>>> Hi Andrew, >>>> >>>> I think it is smart to move over to this way of thinking for releases. >>>> Many of my colleagues here that don't work with Apereo software often >>>> are confused by the releases and how they are organized and I think >>>> this would clear that up. It might be good to adapt a similar strategy >>>> with portlets also, as I see us probably exposing APIs for portlets to >>>> help with mobile app development. >>>> >>>> Aaron >>>> >>>> On Wed, Jun 11, 2014 at 10:23 AM, Andrew Petro <[email protected]> wrote: >>>> >>>>> uPortal folks, >>>>> >>>>> I would like to start floating the Semantic Versioning balloon and see >>>>> if it >>>>> can earn mindshare. >>>>> >>>>> Currently our practice is to add both minor new features / >>>>> enhancements and >>>>> bugfixes in patch releases. >>>>> >>>>> I think our practice should change to bugfixes-only in patch releases, >>>>> and >>>>> do more frequent minor releases to get new features out. >>>>> >>>>> Cf. Semantic Versioning: >>>>> >>>>> http://semver.org/ >>>>> >>>>> Here's the summary: >>>>> >>>>> [ >>>>> >>>>> Summary >>>>> >>>>> Given a version number MAJOR.MINOR.PATCH, increment the: >>>>> >>>>> MAJOR version when you make incompatible API changes, >>>>> MINOR version when you add functionality in a backwards-compatible >>>>> manner, >>>>> and >>>>> PATCH version when you make backwards-compatible bug fixes. >>>>> >>>>> Additional labels for pre-release and build metadata are available as >>>>> extensions to the MAJOR.MINOR.PATCH format. >>>>> >>>>> >>>>> >>>>> ] >>>>> >>>>> I expect that this change in practice would be all upside. >>>>> >>>>> It would make patch releases less risky and less complex, and so would >>>>> make >>>>> it more feasible to cut them more often and for adopters to upgrade >>>>> along >>>>> the patches branch to later patch releases more often. No new >>>>> features to >>>>> figure out how they relate to what you're doing, just bugfixes. >>>>> Easier to >>>>> understand, easier to accept, clearer what you're getting. >>>>> >>>>> It would make clearer what a minor release vs a patch release is and >>>>> why it >>>>> becomes time to cut a minor release and what you get for your minor >>>>> release. >>>>> >>>>> It would move uPortal to align with Semantic Versioning, which is a >>>>> thing. >>>>> Even a good thing. >>>>> >>>>> I'm in-progress cutting the 4.0.14 release, and that's still a >>>>> non-semantic-versioning patch release with some new stuff in it. >>>>> Fine. I >>>>> expect we ought not to change strategies for what the 4.1.x patches >>>>> line >>>>> looks like, since 4.1.0 is scoped and being released under the >>>>> expectation >>>>> that it can be patched with enhancements to backfill gaps. Also fine. >>>>> >>>>> So, if this balloon flies, perhaps the version to adopt Semantic >>>>> Versioning >>>>> in would be uPortal 4.2, and with that in mind we work towards a 4.2.0 >>>>> suitable for treating in this way post-4.1.0-release, and this all >>>>> fits into >>>>> the broader theme of evolving uPortal to be and to be treated more >>>>> like a >>>>> product. >>>>> >>>>> Note that adopting Semantic Versioning says absolutely nothing about >>>>> the >>>>> timeline on which bugfix and new feature releases are released. It's >>>>> just >>>>> about what we call them and how we set adopter expectations about what >>>>> kind >>>>> of changes happen where. There's no rule that we couldn't cut minor >>>>> releases even monthly to promptly get those new features out to >>>>> adopters if >>>>> there's that kind of progress being made in the codebase; calling those >>>>> minor releases is just a clearer way to communicate about what they >>>>> are. >>>>> >>>>> This also fits into a story arc of working towards defining and >>>>> exposing >>>>> versioned APIs. When the codebase is mostly a monolithic bucket >>>>> containing >>>>> both APIs and implementations, nudging them forward all together in a >>>>> patches branch, well, it's mostly worked for us. But if the product >>>>> begins >>>>> to get more deliberate about separating, defining APIs and separating >>>>> them >>>>> from implementations, works to enable better strategies and more >>>>> execution >>>>> on developing plugins with sourcecode not sitting right in the uPortal >>>>> codebase, well, that's going to go a lot better under Semantic >>>>> Versioning. >>>>> >>>>> Kind regards, >>>>> >>>>> Andrew >>>>> >>>>> PS: My endorsement of SemVer does not, of course, imply any >>>>> endorsement of >>>>> its author. >>>>> >>>>> -- >>>>> >>>>> You are currently subscribed to [email protected] as: >>>>> [email protected] >>>>> To unsubscribe, change settings or access archives, see >>>>> http://www.ja-sig.org/wiki/display/JSG/uportal-dev >>>>> >>>> >>>> >> > > -- > You are currently subscribed to [email protected] as: > [email protected] > To unsubscribe, change settings or access archives, see > http://www.ja-sig.org/wiki/display/JSG/uportal-dev > -- You are currently subscribed to [email protected] as: [email protected] To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/uportal-dev
