==== Current state 2022-10-26
- Deprioritizing as we're now announcing "breaking changes" consistently, though we could probably still use the artifacts in the acceptance criteria.
==== Background/Goal
In a June 29 2022 Slack thread, @AnneT and @SimoneThisDot surfaced a risk with regard to our current Codex release communications:
> End users do not have a way to understand how to solve breaking changes. The information provided in the changelog (this was raised as Abstract reached out as they had no idea what to do to fix the breaking changes). Maybe we should have an “breaking changes page” in the documentation.
We discussed a need to add some rigor around our Codex release communications process.
===== User stories
As a contributor, given that I have implemented Codex in my project, I want to access and understand changes to Codex as they are released, particularly "breaking" changes, so that I can take action if needed.
===== Considerations
- T311630 has also been raised; considering this out-of-scope for this task.
- Nuance of merge / NPM / MediaWiki release
- Major version update for breaking changes (when we're in 1.0)?
- Only DST engineers can push Codex releases right now
===== Acceptance criteria
[] MVP Codex release communication plan template for Codex releases has been drafted
[] Template has been reviewed by Design Systems team
[] Feedback has been solicited from current partner teams (Abstract Wikipedia, Growth, Web, WMDE)
[] MVP Codex release communication plan template/checklist has been added to https://www.mediawiki.org/wiki/Design_Systems_Team, as a section or subpage; as well as https://github.com/wikimedia/design-codex/blob/main/RELEASING.md
[] Includes a recommendation for what to do with breaking changes (e.g., https://github.com/wikimedia/design-codex/blob/main/CHANGELOG.md)
===== Open questions
- How can we announce breaking changes with enough time for teams to prepare for them?
- How can we better document breaking changes in the CHANGELOG, e.g. brief instructions on how to handle them?
- Should we include release notes on the docs site, perhaps by creating a page that displays the CHANGELOG?
- How should we announce releases internally for now? Posting in #talk-to-design-systems-team?
- When do we switch over to a wider announcement process; e.g. sending release notes to mailing lists? Beta release? 1.0.0? Can we announce Codex to these wider audiences before the first release notes go out, so that the release notes aren't the first time people are hearing about Codex?
- Who is responsible for executing release comms? Engineer? TPgM? EM? PM?
-- The engineer doing the release, supported on comms, for example on major releases by PM.
- Should we announce on wikitech-l and design-l?
-- Definitely moving forward, we need to increase visibility of Codex releases.