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!

[OmerKahani]

I want to give my personal view:
Currently, the docker depreciation is frightening, as I am not certain what I should do. How can I test if my cluster is using docker? Should I start testing my application using containerd? How should I do it (set up nodes with only containerd)? What would be the upgrade path for an in-cluster upgrade?

I think a guide for end-users who are not reading the KEPs, and maybe even not know what CRI is along with every depreciation, can help make it less frightening and more understandable. a guide that is very operational opinionated.

[justaugustus]

@OmerKahani -- these resources should be helpful:

• Blog post: https://kubernetes.io/blog/2020/12/02/dont-panic-kubernetes-and-docker/
• FAQ: https://kubernetes.io/blog/2020/12/02/dockershim-faq/

[sbueringer]

I think we have at least two distinct target audiences for release notes: Kubernetes cluster operator and Kubernetes users.

The vast majority of the changes are only really relevant for the operators. Maybe it would help to make it easier to filter out user-facing changes. The docker deprecation is not an ideal example of this, in most cases it only affects the cluster operators, except when somebody uses docker build with the host Docker socket.

We're operating an internal Kubernetes-as-a-Service platform and although I (as an operator) find the official release notes pretty useful, the subset which is usually relevant to our users is maybe only about 5% of the whole release notes.

[makkes]

@justaugustus I personally strongly believe that what would take a lot of fear from people is a migration guide answering the question of "How do I migrate my existing K8s cluster setup with Docker to containerd or CRI-O?". Then people would see a clear path forward. Just my $0.02.

[wilsonehusin]

I think we have at least two distinct target audiences for release notes: Kubernetes cluster operator and Kubernetes users.

I totally agree with this. I sometimes get confused myself on who this document is speaking to and where the boundaries are. I think it would be useful if we can further disambiguate this in announcements.

[sftim]

Following #5344 (comment), @makkes I agree and recommend opening an issue in the website repo. (I can or you can).

[justaugustus]

Kubernetes cluster operator and Kubernetes users.

@sbueringer -- it might be helpful to define terms here...

Where do you draw the distinction between "cluster operator" and "user"?

(Maybe naïvely) I would consider "cluster operator" ~= "user".
Concretely, if I'm providing a serving some set of applications to a consumer, the underlying infrastructure should be invisible to them (and the Kubernetes release notes become irrelevant from their lens).

[justaugustus]

Tangential to this issue, maybe a valuable exercise is defining personas?

(and maybe that work already exists...)
cc: @tashimi @hpandeycodeit -- SIG Usability

[justaugustus]

/sig contributor-experience release
/area release-team
/milestone v1.21

[parispittman]

@justaugustus the docs team did persona development. They are defined in the glossary now. Cluster operator, platform developer, etc. unless you are looking for something else/new. https://kubernetes.io/docs/reference/glossary

[justaugustus]

From v1.22 retrospective:
/assign @jlbutler
/milestone v1.23

[nikopen]

how about a dedicated & curated page under https://kubernetes.io/releases/ ?

several levels of importance that I see: Super-wide-reaching changes (e.g. dockershim), other Critical Cluster-Breaking Stuff , etc

Super-wide-reaching changes (e.g. dockershim)
can definitely utilize pro-active blog writing that summarizes the Why and How It Impacts My Clusters parts on the very top
great examples 1 and 2, were written very quickly after the announcement but if created before it would ease part of the panic (maybe)

other Critical-Cluster Breaking Stuff
goal is to pretty-print and summarize the critical cluster-breaking stuff (I would think).
cherry-picking urgent upgrade notes and some wide-reaching deprecations, highlighting the topics can be a good start.
https://kubernetes.io/releases/notes/ just redirects to the long CHANGELOGs which are a bit hard to digest TBH....

other Important Deprecations
etc

coordination can be shared between release-team -> communications-team & docs-team & release-notes-team
i.e.

• Are there any Super-Wide-Reaching changes coming up? if yes, let's communicate the need to write a blog
• paid professional technical writing is an excellent solution
• machine-generated cherry-picking release-notes from GH PRs (i.e. label "cherry-pick-release-note" or similar)
• proofreading of cherry-picked release notes
• curation of cherry-picked release notes
• etc

just some ideas...

[reylejano]

how about a dedicated & curated page under https://kubernetes.io/releases/ ?

Similar but not the same, there is an API deprecation guide on https://kubernetes.io/docs/reference/using-api/deprecation-guide/
This is one of the only pages that breaks the Kubernetes style guide - avoid statements of the future

In 1.22, the Release Team and SIG Docs members published an API and Feature Removals blog after the start of the 1.22 code freeze.
From v1.22 retrospective, this will be part of the Release Team's communication efforts in the release cycle

[sftim]

I'm 👍 on the idea of moving (more like cloning) key release-related information into a page within https://kubernetes.io/releases/ - especially if we can focus on the really important stuff.
That page could link to relevant blog articles, so not just:

• Dockershim is deprecated

and more like:

Notable updates for Kubernetes v2.00:

• The Pod API is deprecated. See Kubernetes without Pods: why we're removing containers for context, or visit migrating to use VMs to learn about migration options.
• The v1 API version of CustomResourceDefinition is no longer available, visit…

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[justaugustus]

@jlbutler -- Have we had a chance to make improvements here?

/remove-lifecycle stale
/lifecycle frozen

[chris-short]

@jlbutler Let me know how I can help here on behalf of Upstream Marketing.

[jlbutler]

Hi all. Sorry, for the latency.

Based on the discussion here, I've added tasks revolving around facilitating an optional "Deprecations and Removals" blog per cycle to the Comms handbook (PR is here if you're reading this and it's still not merged).

We may want to consider something in docs as the above discussion suggests, but at least we've got something in place for every release cycle going forward, rather than ad hoc.

[jlbutler]

Bumping this discussion as relates to other things brought up on the thread beyond the release comms team scope (a dedicated web asset for deprecations and removal, and the higher-level migration support and persona definitions). Do folks want to open these as additional issues, or continue discussion here?

[jberkus]

@jlbutler yeah, creating a "Create a web page with deprecations" issue makes sense. You wanna launch it?