Refining the way we communicate deprecations/wide-reaching changes to the project

[justaugustus]

As we go through deprecations and infrastructure changes in the project, it might be a worthwhile exercise to assess and refine the way we communicate them.

I can think of a few recent examples that caused some panic and required additional lift from contributors to reframe or contort/extend support to accommodate:

• dockershim
• the k8s.gcr.io migration
• hyperkube

We should consider what it means to turn down a service, piece of functionality, or kubernetes/kubernetes-adjacent system and type of impact it may have for consumers.

Without policing contributors, as maintainers of the project, we also have a responsibility to users to be careful and deliberate with our communications outside of the project, whether it be Twitter, Hacker News, etc., etc.

So how can we improve?

I think depending on the scope of a change, the following SIGs should be involved in crafting comms:

• @kubernetes/sig-architecture
• @kubernetes/sig-release
• @kubernetes/sig-docs-en-owners

With @kubernetes/sig-contributor-experience to assist with consistent delivery.

I'm curious to hear everyone's thoughts here.

cc: @kubernetes/steering-committee

[parispittman]

can this be added to the release team communication role with assist from contributor-comms cc/ @mbbroberg for amplification, promotion, and education?

[justaugustus]

xref note to k-dev + Steering: https://groups.google.com/g/kubernetes-dev/c/B0mPMpDLVk4

[Katharine]

My generalised take on the latest adventure, without attempting to police personal contributor tweeting:

The people who write end-user-facing release notes (particularly for changes with action required, e.g. deprecations) should probably not be the the people who wrote the code: they carry a substantial amount of context that the average person does not have, and that is fairly likely to leak in to what they write. At the very least, some people specialising in communications or docs should probably carefully review all such notes.

[justaugustus]

can this be added to the release team communication role with assist from contributor-comms cc/ @mbbroberg for amplification, promotion, and education?

@parispittman -- Yep, I think that sounds great, with that caveat that the Release Comms subteam can be a conduit to merging the various communications streams, but the respective SIG/subproject/component area is on the hook for providing the context that should communicated.

[justaugustus]

At the very least, some people specialising in communications or docs should probably carefully review all such notes.

THIS. THIS. THIS.

[jeremyrickard]

Big +1 echo to what @Katharine said.

can this be added to the release team communication role with assist from contributor-comms

I think so, but like @justaugustus said I think the content responsibility of the owning SIG and it's a partnership with sig-docs. To be honest (having been through a few cycles on the release team now), I think we struggle sometimes to get important things like docs and major themes in/ready sufficiently early to make sure we can communicate things correctly before they show up and hit the wild. We'll add this as a retro item for the 1.20 retro to see what we can discuss and get better for 1.21!

[dims]

I don't think we need steering sign off on this. Cc is fine :) thanks for that!

[reylejano]

I believe that deprecations in a release should be identified by the appropriate release team role as early as possible so that the appropriate sig can prep, review, release the communications. The timeline to release communications should be cognizant of the availability of the changelog prior to the official release date.

[celestehorgan]

As a general rule: industry standard is to communicate a minimum of 6 months out (1+ year is better) from date of deprecation to date of removal. It's considered polite to communicate a schedule as soon as the descision is made, I.e.

• in release x.y.1, feature a is deprecated. It will be removed in feature x.y.3. Use feature b instead.

Which is what the console log does: the minimum is to communicate timeline and replacement if any.

Standard is also to call out any deprecations in a release notes section (i.e. under major themes, a section titled Deprecations). A good idea is also either writing a blog post or having a section on the website for deprecation notices.

[justaugustus]

I believe that deprecations in a release should be identified by the appropriate release team role as early as possible

@reylejano -- to refine this a little: the owning SIG should signal to the Release Team that a deprecation is happening and that we all need to help prepare comms for it. The onus SHOULD NOT be on SIG Release to sift through issues and PRs to identify something that a SIG reviewer/approver [sh|w]ould have direct context on.

[jeremyrickard]

I believe that deprecations in a release should be identified by the appropriate release team role as early as possible so that the appropriate sig can prep, review, release the communications

I agree, with a caveat. We tracked a couple of deprecations this time around, but the dockershim one wasn't actually in the 1.20 Enhancement Sheet. The current enhancement collection/tracking is really dependent on kubernetes/enhancements issues. The dockershim KEP actually went in as a PR w/o issue and it's easy to miss this stuff. The release team can't sift through all the PRs and stuff that go in to find these, we need to have that affirmative confirmation that something is going to be deprecated (and hence in the release) so we can connect all those dots, vs trying to connect all the dots and make sure we are covered at the end of the release.

[lachie83]

Just an idea - Could we leverage the Comms team as part of the release team to manage deprecation Comms for that release? They could potentially work on these announcements prior to the release date once code and docs have made it into the release.

[kikisdeliveryservice]

This time around, I specifically tracked deprecations in the tracking sheet (they that had open issues and actively participated in the enhancements process) bc I wanted to be able to highlight them to docs or comms at a glance. I think it's worth mentioning that all KEPs need issues and that non-trivial deprecations probably need a KEP (and a tracking issue/participate in the release process). Also strongly agree that it's simply not possible (or desirable) for the RT to dig thru PRs to match things up - we need authors and sigs to actively & fully participate in the release process.

That said, I think we should consider having an explicit deprecation "graduation" criteria in the KEP template. We need to think about requiring what we need to effectively communicate deprecations in the KEP itself - those are equal requirements to k/k prs imo. That could include: officially announcing the intent to deprecate with help from comms, some guidance of x releases between that initial announcement and beginning the rollout, an explicit rollout calendar with all required comms milestones, etc.. (I made this up, I'm sure people have better ideas 😉 ). I think it's well within our ability to think this through and come up with a way to adequately track what we collectively need, ensure it gets done and have that reflected in the KEP (which is the durable artifact for features/deprecations anyway - why not use it?).

Happy to talk about the above more and brainstorm if anyone is interested!