2025-07-16 Breaking changes decision making and communication

1 min

Scribe

All

@Christie Thomas

Reminder:  Please copy/paste the Zoom chat into the notes.  If you miss it, this is saved along with the meeting recording, but having it here has benefits.

*

Breaking changes

All

Prior work from TC:

• https://github.com/folio-org/rfcs/blob/master/text/0003-folio-breaking-changes.md

• https://folio-org.atlassian.net/wiki/spaces/TC/pages/5057118/DR-000036+-+Breaking+Changes

• https://folio-org.atlassian.net/wiki/spaces/TC/pages/43582046/2024-02-21+-+Communicating+Breaking+Changes

Current related discussion:

• https://folio-org.atlassian.net/browse/MODINVSTOR-987

• https://github.com/folio-org/ui-courses/pull/349

• https://open-libr-foundation.slack.com/archives/C210RP0T1/p1751545657842059

Discussion:

Guidelines for when to make a breaking change. / Communication with the community after a decision has been made to make a breaking change.

• When in the dev cycle to make a breaking change?

• When is a breaking change the right engineering decision?

• Is there something broken in the way that these decisions are incentivized? Complexity can be shifted from one team to another without agreement.

• Need to determine who bears the burden/cost associated with a breaking change. The burden of these changes rarely even across teams and it can be challenging to express impact across teams.

• Are there communication protocols that can be put in place? Is TC the correct agent for providing these protocols. TC was asked for advice on this issue.

• There are communication suggestions that have been put forth. Did the friction arise because of the suggestions themselves or the process? Can the process be improved to reduce friction and improve reception?

• One aspect that could have been improved in the message - changing the wording and making the request more accommodating in terms of timeline to reduce the sense of urgency around the change.

• Who is responsible for making required changes after a breaking change? The team that made the breaking change or the team with responsibility for other modules?

• When are breaking changes announced? During the discussion phase before a decision is made? Transparency allows for other teams to anticipate changes.

• Concern about slowing down work or stopping work altogether if community consensus on a change or team cannot be aligned on timing the work. This requires a culture change. Culture is different in this area for UI because it is smaller and less complex that the backend modules. There are just fewer of them.

• Turn recommendations around communication into actual policy that TC endorses and pushes out to the community? Is a policy appropriate? Guidelines or advice? What are the practical differences?

• A part of this guidance needs to communicate the expected process is for breaking changes.

• Are there recommendations that can be made regarding appropriate context that needs to accompany breaking change communications so that decisions can be made faster.

• Does the TC need to make statements about who is responsible for what? Recommendation to make statements on the what and why of a change.

• Goal should be to reduce the burden on the community to make decisions and manage changes throughout FOLIO.

• Action item: @Jenn Colt will work on a document: Breaking Changes Communication Guidelines.

• Question about the PR in question. In this case the TC has been asked to weigh in. There are lessons that can be learned from this example and can be used to inform guidelines to improve the process in the future. Without weighing in on whether or not this is the correct change and without reviewing the code, there is nothing that has happened that is outside of the process for breaking change and the TC can recommend moving forward.

• Discovery issue - teams are not reading TC minute notes to understand how they are supposed to behave. Distinguish between norms of the community and published guidelines.

• TC needs to acknowledge that we cannot hold teams to standards when we have not done all we can to communicate those standards.

• TC will work on discovery of documentation in the future.

-

Zoom Chat

Wayne Schneider (Jul 16, 2025, 10:03 AM)

Is the Zoom link in the ics file for the "dedicated discussion" meetings incorrect? When I connected I got the message that the meeting had been ended

Khalilah (EBSCO) (Jul 16, 2025, 10:07 AM)

Apologies for the delay.

Craig McNally (Jul 16, 2025, 10:19 AM)

If not the TC, then who?

Shelley Doljack (Jul 16, 2025, 10:21 AM)

Apologies for being late.

You (Jul 16, 2025, 10:38 AM)

Thank you!

Thomas Trutt (Jul 16, 2025, 10:39 AM)

What constitutes a significant change in this context though?

Wayne Schneider (Jul 16, 2025, 10:40 AM)

Does it need to be a policy, or really guidelines or advice as Jenn is saying?

Marc Johnson (Jul 16, 2025, 10:41 AM)

I don’t think there is much practical difference

Wayne Schneider (Jul 16, 2025, 10:41 AM)

Policy suggests enforcement which of course we can't do.

Marc Johnson (Jul 16, 2025, 10:42 AM)

Was it a false sense of urgency (from the team making the breaking changes perspective)?

Craig McNally (Jul 16, 2025, 10:42 AM)

I think timing was a factor here.  The announcement was made after the changes were made and a PR were opened.  I'm not sure how much it would have helped if the conversation was started earlier, but it sounds like we're advocating for comms as early as possible

Maybe that's something worth adjusting in the guidelines/policies...

Marc Johnson (Jul 16, 2025, 10:49 AM)

I think that makes it even more important we make it explicit which team is responsible for what

Craig McNally (Jul 16, 2025, 10:54 AM)

wrt "we" I've been doing that too Marc...  habits

Marc Johnson (Jul 16, 2025, 10:55 AM)

Olamide is also correct about the discovery challenge

Craig McNally (Jul 16, 2025, 10:57 AM)

Well both parties are asking for the TC to weigh in on this

Marc Johnson (Jul 16, 2025, 11:00 AM)

Weigh in on whether the change is right or whether the way folks went about it is right?

Zak Burke (Jul 16, 2025, 11:03 AM)

I feel like the request in the PR thread is, “Do I really have to make this decision?” And the answer can be “Sorry but yes, ya gotta deal with it.” That’s not a formal PR review (to Wayne’s point), but is still an endorsement.

Wayne Schneider (Jul 16, 2025, 11:04 AM)

Even if the TC did put out guidelines at some point a timely reminder would seem to do no harm

Khalilah (EBSCO) (Jul 16, 2025, 11:05 AM)

If POs can help with communication, please let me know.