SemVer -- What are breaking changes?

[Benito Gonzalez]

Hi devs,

Let's have a discussion about what are breaking changes for uPortal. It seems like a simple answer -- anything that causes an implementer to rework some build artifact(s).

Here are some grey areas I would like us to review:

1. Database -- Hibernate can automatically add new tables, columns and the like. If we change or add a table and it can be updated without human intervention, is this no longer a breaking change?

2. Java code -- Just pointing out that custom Java code might break with any feature or fix, so changes to Java code shouldn't be considered "breaking". But OTOH what if we completely redesigned or rewrote a uPortal module? What if I rewrite a module in Clojure or Scala?

3. Data file defaults/requirements -- we had a new permission that needed to be specified in portlet definitions. At the time this was not considered a breaking change even though a majority of these files needed to be updated. Still, the definitions were imported correctly as they were. If a default changed or a new required attribute was needed, I would consider it a breaking change. Thoughts?

4. We have some "test" portlets that really have little value. When we take this out, will it be a breaking change? What about upgrading bundled CAS from 3.5 to CAS 6?

5. APIs -- enhancing existing APIs is not breaking. Consumers of the APIs should not break if a new value is added to JSON output. Breaking changes would be removing some expected value or removing/moving a deprecated API.

6. Skinning (CSS) -- skinning is about CSS to style the portal HTML. We had to modify classes and some of the HTML for accessibility. This broke several skins, so upgrading from uPortal 4 to 5 was challenging in this area. Since everyone has a custom skin, I consider HTML modifications to be breaking changes.

7. Theme XSL files -- These are the files that convert the layouts to HTML (or JSON for some APIs). While a few implementers customize these to change HTML, my view is that this is closer to code than skinning. If we replace these XML files with an HTML templating engine, would this be considered breaking or enhancement if the HTML was completely the same?

So these are some thoughts to kick off discussions. The importance of documenting our decisions is to inform implementers what might change in a feature release versus a major release. My other hope is that this will spur those with customizations into donating them to the community. In this way, customizations become features that are maintained in future upgrades.

-bjagg

--

Benito J. Gonzalez

Software Architect

Unicon, Inc.

209.777.2754

Email:  bgon...@unicon.net

GitHub:  bjagg

GitLab:  bjagg

BitBucket:  bjagg

[Jackson, Allan]

I don’t have specific answers to all of these, but I do have a couple thoughts to add.

 

I’d like to see some sort of “what extra steps do I need to update to this version” section in the release notes. I imagine this would cover some of the points from your email such as a database tweak or a new data file that needs to be imported. If this “extra steps” section is simply running a couple of predefined commands, I wouldn’t really consider that a breaking change. To me a breaking change would be more like something where I might have to figure out and make a change to some of my code.

 

Another thing that worries me about upgrades is if there is an upstream change to a file I’ve written an overlay for. Ideally there would be some automatic mechanism for that change to make its way down into my uportal-start code, but that sort of solution would probably be a lot of work to implement. As it stands now, I’ll basically just never know there’s a new version of a file, and I’ll be stuck with the old one. A prime example of this is the Messages.properties file. We have a couple tweaks to that file, so now we’ll never automatically get updates to it again.

 

Allan

--
You received this message because you are subscribed to the Google Groups "uPortal Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to uportal-dev...@apereo.org.
To view this discussion on the web visit https://groups.google.com/a/apereo.org/d/msgid/uportal-dev/CAJ_1GkShX2Wk7CLiUZCWv-Y7ayiPFc-rYyatn5napV0549p3%2BQ%40mail.gmail.com.

[Benito Gonzalez]

Allan,

Thank you for the feedback. We can certainly add such a section to the release notes. This could really help implementers identify the time and resources to adopt releases.

Yes, bringing in a file into an overlay directory certainly flags it for future conflicts. We were hoping this would keep the number of customized files to a reasonable number for manual review. Also, having them explicitly captured in a well known way avoids the previous approach of wading through every code change. Still, that would be pretty cool to have a gradle task that performs a diff against Github to display what's changed.

Great feedback!

-bjagg