community

community copied to clipboard

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

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

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

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.

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.

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

THIS. THIS. THIS.

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!

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

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.

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.

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.

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.

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.

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!

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.

@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/

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.

@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.

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.

Following https://github.com/kubernetes/community/issues/5344#issuecomment-737751369, @makkes I agree and recommend opening an issue in the website repo. (I can or you can).

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).

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

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

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

@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

@parispittman -- no, that's perfect to potentially frame buckets of release note "types" (if that's something we decide we want to slice against). Thanks!

@justaugustus I think it's hard to differentiate sometimes.

My personal experience: We're providing the cluster, our users/customers get a kubeconfig file and can then almost do whatever they want with their cluster (via kubectl, not via ssh). Providing includes: creating/updating/deprovisioning the cluster and monitoring the control plane and node health (this is where it get's blurry :)).

I think this somewhat aligns with what public cloud providers like GKE/EKS/AKS offer.

To me, users mostly care about things like API changes and deprecations (e.g. extensions/v1beta1 => apps/v1). What they usually don't care about are things like kubeadm changes. In my experience they usually just don't have the knowledge to interpret all the other "internal" changes.

Regarding the glossary. In our case:

• operators: Cluster Operator, Cluster Architect, Platform Developer, Code Contributor
• users: Application Architect, Application Developer

Maybe tl;dr is: above vs below the Kubernetes API (in the sense of kube-apiserver), but that oversimplifies it quite a bit

I'm not sure if it's a a good idea to separate release notes like this, but just wanted to bring up the idea.

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

I created https://github.com/kubernetes/website/issues/25371. This is my first issue on that repo so please bear with me in case it's not as complete as expected.

I think that we're combining two issues here: 1) how to ensure that deprecations will be adequately communcated from the authors/sigs to the rt to the community and 2) what kind of communication that should be.

In practice, without having number 1(which I talked about earlier) we simply don't have the room to figure out what 2 should look like bc the comms that various deprecations need can only be standardized to a certain extent - some will vary based on impact, but all will require collaboration between the sigs/authors/rt/docs/comms which takes time in a already busy release cycle. If we want more precise or nuanced comms and strategy, we really do need to come up with how this should work to guide sigs and authors and ensure that there's adequate time to get it all done.

Usually the EOL for a feature or product gets done by PM’s in collaboration with other teams like comms/doc etc. The best way i have seen it work is using a cascading method where the sig associated with the change (like dockershim deprication) could communicate to other sigs well before in hand. Each sig would then get a chance to evaluate the impact of the change and have a write up/ Communication on any potential gotchas that the customers should be aware of. This way, we would end up calling out all potential impact that the major change would have on customers.

The last thing is to give a heads up to customers on the time they would have before the major change becomes the default behaviour on the platform. My$0.02

@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/

Thanks,

I used the docker as an example, I can make the same list for the depreciation notice in 1.16.

I wanted to emphasize that this kind of notice should come with a tactical guide including:

• What are the required tests
• How can I find what I need to change in my cluster (what objects / configuration)
• What I should check with my application
• What is the upgrade path
• The timeline for complete removal
• If I find errors or problems where I can get help

Most of the folks in this thread stay up to date with this stuff and at this point in time this news is at the forefront. However, I think it's important to come up with a mechanism to remind and inform operators who may not hit these deprecations for another year or more. The kubectl warnings have been nice, could there be some mechanism for doing the same with these larger deprecations?