1842850 - Implement a manual changelog of design tokens for communicating change

Status: RESOLVED WONTFIX

(Toolkit :: Themes, enhancement)

Description

[Jules Simplicio [:jules]]

To help us track changes so that people who consume and contribute to design tokens are aware of new design tokens or changes, and why.

Comment 1

[Jules Simplicio [:jules]]

Attachment: WIP: Bug 1842850 - Implement semantic versioning and changelog of design tokens

Comment 2

[Jules Simplicio [:jules]]

Attachment: Bug 1842850 - Implement semantic versioning and changelog of design tokens

Comment 3

[Dão Gottwald [:dao]]

Hmm, so version control is already at the heart of our code base. E.g. the change log for tokens-shared.css is here: https://hg.mozilla.org/mozilla-central/log/tip/toolkit/themes/shared/design-system/tokens-shared.css
There's also blame information next to each line here: https://searchfox.org/mozilla-central/source/toolkit/themes/shared/design-system/tokens-shared.css
Clicking on a bug linked there should give you all the information you may need.

Do we really need versioning and another change log on top of that?

Comment 4

[Jules Simplicio [:jules]]

Hey Dão, that's a great point. I chatted briefly with Mark (:mstriemer) about this and we are also thinking that since this isn't treated as a package and other teams/contributors aren't consuming it, and since we don't have any sort of automation in place and all, or at least not yet, that we agree that it doesn't make quite sense to control it with a version.

We feel as though however that it's still valuable for people to see notable and recent changes in a more human readable format. For example, Mark's button patch will introduce quite a bit of tokens, and it may be nice to be able to add a more proper message around it beyond seeing the 'add moz-button component' in the history and having to look through those files. In addition I am hoping this will help continue to advocate for the tokens effort and to continue giving it more traction, and for us to also continue being very transparent about progress.

We're thinking about instead treating this as a more simple documentation such as "Recent/notable changes to tokens" only local to/inside Storybook docs. Still a bit of a manual process that will fall on me and my teammates, but I do see value in being over-communicative about token updates and having a simple document we can point people to.

How do you feel about this approach for now?

Comment 5

[Dão Gottwald [:dao]]

(In reply to Jules Simplicio [:jules] from comment #4)

We're thinking about instead treating this as a more simple documentation such as "Recent/notable changes to tokens" only local to/inside Storybook docs. Still a bit of a manual process that will fall on me and my teammates, but I do see value in being over-communicative about token updates and having a simple document we can point people to.

How do you feel about this approach for now?

Are you saying folks wouldn't be expected to update those docs? I wouldn't want to put up a burden to contributors outside of the team. If you're going to keep the log updated transparently, then I see no problem with that.

Comment 6

[Jules Simplicio [:jules]]

Thanks! I changed the title and will edit my work so it doesn't imply this is a versioned controlled resource and that contributors also need to maintain it.

Comment 7

[Jules Simplicio [:jules]]

Closing this bug as dao, sfoster, hjones and I discussed this topic last week and we made a decision to lean on the codebase's changelog.

We will be enforcing meaningful summaries on commit messages, and there will be a few outlets where me and the Reusable Components team will share any major design tokens updates: bi-weekly Firefox desktop meetings, desktop dev update emails (major changes like introducing tokens and typography have already started getting listed in these emails under the Reusable Components project heading), and #acorn-design-system Slack channel.

Marking this as wontfix unless another status is better - feel free to fix!

Thanks all!