[Umbrella issue] Investigate and create a communications plan for disruptive changes

[shannonxtreme]

Describe the issue

In the past, we've needed to communicate upcoming disruptive changes to the project to end users. For example, deprecating dockershim or the registry changes. We lack a comprehensive process around communicating this type of disruptive/breaking change to our users. This issue proposes the creation of a comms plan, including performing an audience needs analysis, creating templates, and accounting for crisis situations.

The rest of this issue is up for discussion. I split it into phases to make it easier to track this effort in individual issues. If the scope is too large, we can work on it. I also am unsure who would own what part of the comms process.

Goals

• Reach the maximum number of end users with comms about disruptive changes, especially those without a direct line to the k8s community
• Understand the effort and lead time required by the majority of end users to migrate from the deprecated capability
• Create consistent, unified comms and documentation, at predictable times, for every new change to the project

Tasks

Phase 1: Gather information

(TODO: tracking issue)

• Survey our end-users to understand their needs
  • How do they stay on top of project changes?
  • Where would they ideally find these changes?
  • How long do they need to prepare their environments for disruptive changes? (how long did it take for recent ones?)
  • What type of guidance do they need from us? (how much hand-holding, how much context, what type of docs)

This phase's methodology is up for discussion. What media do we use to get a survey to people?

• Social media (Twitter, LinkedIn(?), Reddit, Mastodon, TikTok)
• Banner on kubernetes.io
• Where else?

Phase 2: Identify cloud provider stakeholders

(TODO: tracking issue)

Communicating disruptive upstream changes should be a partnership with cloud providers, which'll increase our reach with every communication.

• Identify internal stakeholders at various cloud provider organizations
• Ensure that cloud provider stakeholders know how their org's comms process works (release notes/social media/blog posts)
• Include interested stakeholders in comms planning for disruptive changes

Consider making this process timeless by asking the stakeholders to set up aliases instead of relying on individuals.

Phase 3: Build a plan

(TODO: tracking issue)

Create a baseline communications plan. This plan needs to outline the following:

• Stakeholders (project and cloud provider)
  • Includes owners for deliverables
• Timeline and milestones. Includes but not limited to:
  • When to create the initial tracking issue
  • Minimum time period before full removal
  • When to deliver specific deliverables
• Modes of communication based on survey results
• Core deliverables based on survey results. For example:
  • Migration guide (P1)
  • "Hub" page about the change that includes context, links, etc (P1)
  • Blog posts (P2)
  • Release notes announcement (P1)
  • Comms schedule (P2)
• Crisis comms plan:
  • Minimum viable content for a crisis situation
  • Minimum stakeholders to resolve the immediate issue
  • Highest engagement platforms to send out communications
  • Creation of tracking issue to feed into the full comms process

Phase 4: Templates and process docs

(TODO: tracking issue)

Process docs

• SIGs: How to engage the comms subproject(?)
• Comms team:
  • When to use crisis plan vs normal comms
  • How to use the comms plan
  • How to engage stakeholders (setting up meetings, etc)

Templates

• Template for initial tracking issue
• Template for migration guide and "hub" page
• Template for comms schedule (spreadsheet with posts and frequency)
• Template for release notes announcements

Example flow

Consider an upcoming planned deprecation of PodSecurityAdmission. sig-security creates an issue with the comms folks with the following info:

• What's happening and why
• Alternatives
• Expected timeline

Comms + the SIG:

1. Fill out the comms plan with all the info in the template
2. Create a tracking issue for the change and attach the comms plan
3. Set up recurring meetings at a set cadence with stakeholders
4. Draft the P1 deliverables (migration guide, hub page, comms schedule)
5. Create issues or PRs with sig-docs to update docs, engage cloud provider stakeholders, etc
6. Announce the change with release notes and identified social media. All announcements link to hub page.
7. Use the comms schedule to plan reminders and P2 deliverables (FAQs, blog posts)
8. After the minimum allowed time (eg: 1 year) has passed, finalize the change.

[k8s-ci-robot]

@shannonxtreme: The label(s) sig/contribex cannot be applied, because the repository doesn't have them.

In response to this:

/sig contribex

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[shannonxtreme]

/sig contributor-experience

[shannonxtreme]

/cc @IanColdwater @chris-short @mrbobbytables @kaslin

[k8s-triage-robot]

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

This bot triages un-triaged issues 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 as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

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

/lifecycle stale

[k8s-triage-robot]

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

This bot triages un-triaged issues 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 as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

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

/lifecycle rotten

[k8s-triage-robot]

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

This bot triages issues 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:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

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

/close not-planned

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue, marking it as "Not Planned".

In response to this:

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

This bot triages issues 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:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

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

/close not-planned

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[BenTheElder]

/reopen
/remove-lifecycle stale
cc @kubernetes/contributor-comms

Thinking of this as we're discussing cgroups v2

[k8s-ci-robot]

@BenTheElder: Reopened this issue.

In response to this:

/reopen
/remove-lifecycle stale
cc @kubernetes/contributor-comms

Thinking of this as we're discussing cgroups v2

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[BenTheElder]

xref: kubernetes/enhancements#4572

[SergeyKanzhelev]

I think this issue description is missing a big area that we need to be better about is a community of thrid party tools built on k8s. Many customers don't care about k8s internals, they depend on it by proxy via those 3rd party tools. Spreaading awareness in CNCF and beyond is a very important job we need to do when making disruptive changes

[SergeyKanzhelev]

/remove-lifecycle rotten

[chris-short]

@SergeyKanzhelev One thing we learned from the registry change comms effort is that many folks found out about it through their Kubernetes/cloud vendor. Building good links between K8s Comms and the cloud providers went a very long way. The fact this is listed towards the top is VERY good.

Taking your comment into consideration, how much further should we go? I want to have some kind of idea of scale here so the effort can be measured accurately.

[shannonxtreme]

@SergeyKanzhelev One thing we learned from the registry change comms effort is that many folks found out about it through their Kubernetes/cloud vendor. Building good links between K8s Comms and the cloud providers went a very long way. The fact this is listed towards the top is VERY good.

Taking your comment into consideration, how much further should we go? I want to have some kind of idea of scale here so the effort can be measured accurately.

To this point, how do third party tooling devs (not the cloud providers) keep up-to-date with what's going on in k8s? Is the expectation that they be on our dev mailing lists and in our Slack channel? At what point is the onus no longer on the project and more on the 3p developers to ensure that they're subscribed to our major channels (and how can we socialize those channels more?)

[SergeyKanzhelev]

@SergeyKanzhelev One thing we learned from the registry change comms effort is that many folks found out about it through their Kubernetes/cloud vendor. Building good links between K8s Comms and the cloud providers went a very long way. The fact this is listed towards the top is VERY good.

Taking your comment into consideration, how much further should we go? I want to have some kind of idea of scale here so the effort can be measured accurately.

Yes, cloud vendors is the best and the most immediate and higher priority communication channel we need to ensure. Especially since many of them needs to be conformant: https://www.cncf.io/training/certification/software-conformance/ which assumes timely updates.

As for 3rd party vendors, I think a good story may be if we will have some comms channel for people building products that "work on k8s". Including monitoring vendors, security vendors, frameworks, etc. If for every deprecation we may contact 3rd party vendors and publish table with the name of a 3rd party product and a link to the product's page explaining how the deprecation affects or doesn't affect them - it will be great. Something that we can generate sceleton for and vendors can fill up with their links, would be great to have

[SergeyKanzhelev]

BTW, same idea as in previous comment can be used for conformant products. For each deprecation we can ask every conformant vendor to provide a docs link and indication on their readiness for the deprecation.

This will be a very good use of a conformance program as I see it.

[chris-short]

@kaslin and I will likely spend some time after the comms meeting next at least getting some bullet points together.

[k8s-triage-robot]

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

This bot triages un-triaged issues 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 as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

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

/lifecycle stale

[k8s-triage-robot]

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

This bot triages un-triaged issues 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 as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

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

/lifecycle rotten

[SergeyKanzhelev]

/remove-lifecycle rotten

seems to be still needed.