A procedure for communicating breaking changes is needed

[consideRatio]

In #3015, the idea is surfaced to introduce a "breaking change" for the jupyterhub deployments. In this case, its the idea to configure a max session duration for a user server to act as a safeguard from failing to scale down.

In this issue I want to highlight that we have a need for handling a "breaking change" like this, because it would be breaking. Maybe some communities want a change like this, but I know that not all wants it - and introducing it could do significant harm.

I think we need a procedure to handle a situation like this.

Situations to consider

• Maintenance of dedicated / shared clusters causing downtime for communities
• Making a change like Considerations of max user session lifetime #3015, setting an upper limit on the duration of a user session

Related

• Procedure for emailing all community representatives #3048 - a smaller scoped issue about emailing specifically

[damianavila]

cc @colliand and @jmunroe who should be involved in this sort of communication with the communities.

[colliand]

Thanks @consideRatio for creating this issue. Within current constraints, I'll share some guidance here since we don't have bandwidth to develop a carefully considered policy.

2i2c (and the upstream communities we rely upon) delivers services and software with a variety of parameters. Some of these are promised as part of our service agreement. Some are explicit in our documentation and service descriptions. Others are more implicit, visible in the code base but not highlighted in business documents.

2i2c must not introduce "breaking changes" that break promises in service agreements.

2i2c should not break expected services in our product/services description.

2i2c can introduce "breaking changes" on implicit parameters but should consider impacts on our partner communities. Changes that may generate "significant harm" require care and communication.

2i2c must track these changes to diagnose and resolve issues and bugs that may be caused by the changes.

[consideRatio]

Thank you @colliand!!

I think you've answered a related topic we needed to answer also, but not exactly what i was looking for.

Changes that may generate "significant harm" require care and communication

What I'd like is to understand is how to go about making a change like this. I think #3042 could be seen as such change, but how do we then communicate about it if we've decided to go for it?

I proposed that we would write relevant docs and send an email to all community champions, but we've perhaps never done something like it right?

[colliand]

I like the proposed plan. That said, I miss enough email to wonder if this strategy is enough. Can we also use "in Jupyter lab" banners? I imagine logging into the hub, seeing a banner with info on the breaking change, and a hyperlink pointing to the documentation.

[consideRatio]

@colliand thanks for thinking with me about this!!

We could add banners (aka. announcements) for JupyterHub's views (login view, start server view, admin panel view), but not for JupyterLab as that is the user environment. This is something we've already done and know how to do, but there are practicalities on emailing community representatives that I don't know how to do. I opened #3048 to focus on that.

About making announcements:

• Document how to make a maintenance announcement features#24

[yuvipanda]

We have a list of community representatives to email now, and have used it. Any further work should go through the product development process.