Build communication framework for Codex releases
Open, Needs TriagePublic
Actions

Assigned To

None

Authored By

	ldelench_wmf
	Jul 5 2022, 8:09 PM

Description

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.

Details

Subject	Repo	Branch	Lines +/-
Update Codex from v0.2.1 to v0.2.2	mediawiki/core	master	+1 K -1 K
docs: Add note on what a 'breaking change' means	design/codex	main	+13 -8
docs: Add step to releasing docs to document breaking changes	design/codex	main	+13 -0

Customize query in gerrit

Related Objects

Mentioned In: T312165: [EPIC] Design Systems Team Communication Improvements Q1 2022-23
Mentioned Here: T311630: Consider allowing MediaWiki projects to pin a previous version of Codex

Event Timeline

ldelench_wmf created this task.Jul 5 2022, 8:09 PM

ldelench_wmf mentioned this in T312165: [EPIC] Design Systems Team Communication Improvements Q1 2022-23 .Jul 7 2022, 9:03 PM

ldelench_wmf triaged this task as Medium priority.Jul 18 2022, 1:26 PM

ldelench_wmf updated the task description. (Show Details)

ldelench_wmf moved this task from Inbox to Needs Refinement on the Design-System-Team board.

ldelench_wmf added a subscriber: SimoneThisDot.

ldelench_wmf removed a project: Epic.Jul 18 2022, 1:36 PM

ldelench_wmf updated the task description. (Show Details)Jul 18 2022, 3:58 PM

AnneT updated the task description. (Show Details)Jul 18 2022, 4:13 PM

Change 816859 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Add step to releasing docs to document breaking changes

https://gerrit.wikimedia.org/r/816859

gerritbot added a project: Patch-For-Review.Jul 25 2022, 9:58 PM

Change 816859 merged by jenkins-bot:

[design/codex@main] docs: Add step to releasing docs to document breaking changes

https://gerrit.wikimedia.org/r/816859

How can we announce breaking changes with enough time for teams to prepare for them?

Once Codex is stable and our version numbers follow semver(*), we could consider OOUI's practice of doing a "deprecating change" in one release, followed by a "breaking change" in the following release.

For example, let's say that, some time after releasing Codex 0.1.2, we decide we want to change the foo prop from a string to some sort of complex object type. We would do the following:

In version 0.1.3, change the type of foo to the complex object type, but still accept strings for backwards compatibility. If a caller passes in a string, it still gets the same behavior it got in version 0.1.2, but it also gets a warning saying that passing in a string is deprecated and that it should pass in an object instead. Announce this as a "deprecating change".
In version 0.2.0, remove the backwards compatibility code. Passing in a string now results in an error. Announce this as a "breaking change".

This way, users of the library can upgrade to 0.1.3, see the warnings, update their code, then upgrade to 0.2.0, all without anything breaking and without us needing to coordinate a series of commits across many repos that all need to be merged at the same time.

(*) We'll have to think about the implications of real semver, because it means you have to increment the major version every time you make a breaking change. If we were on version 1.2.3, then a deprecating change would take us to 1.3.0, and a breaking change to 2.0.0. This is both good (because it discourages us from making breaking changes) and bad (because it makes it more annoying to make breaking changes when we do need them). OOUI has stayed on 0.x.y (which allows breaking changes between e.g. 0.5.2 and 0.6.0) and never gone to 1.0, but we probably do want to do a 1.0 release at some point. When we do that, we'll have to get a lot more serious about stability and backwards compatibility.

For now, however, while we're still on -alpha or -beta versions, I think we can make breaking changes a bit more liberally. But it would still be a good idea to start practicing the deprecating change + breaking change pattern, because that makes it easier for library users to deal with these changes. Instead of using the traditional semver style, we'd make a deprecating change in 0.1.0-alpha.12 and the corresponding breaking change in 0.1.0-alpha.13, for example.

Maintenance_bot removed a project: Patch-For-Review.Jul 28 2022, 12:31 AM

Change 832360 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] docs: Add note on what a 'breaking change' means

https://gerrit.wikimedia.org/r/832360

gerritbot added a project: Patch-For-Review.Sep 20 2022, 2:11 AM

Change 832360 merged by jenkins-bot:

[design/codex@main] docs: Add note on what a 'breaking change' means

https://gerrit.wikimedia.org/r/832360

Maintenance_bot removed a project: Patch-For-Review.Sep 21 2022, 2:30 AM

Volker_E updated the task description. (Show Details)Oct 25 2022, 7:08 PM

Change 849191 had a related patch set uploaded (by VolkerE; author: VolkerE):

[mediawiki/core@master] Update Codex from v0.2.1 to v0.2.2