USWDS-Site - Changelog: Create mockup with real content

[amyleadem]

Summary

Gathered changelog data for the banner component to stress test the current data structure and changelog presentation.

Related issue

Closes #1776

Related PRs

This PR builds on previous changelog PRs:

• USWDS-Site Changelog prototype https://github.com/uswds/uswds-site/pull/1753
• Changelog.md template https://github.com/uswds/uswds-team/pull/207

Additionally, this incorporates the data structure proposed in the notes in Issue #1787

Preview link

Preview link: Banner changelog

Problem statement

The proposed changelog structure needs to be stress tested with real data to confirm that the structure will be usable and provides the optimal user experience.

Solution

Methods

I performed the following tasks to gather changelog data:

• Searched USWDS release notes for the word "banner".
• Read through release notes to see if there are items related to banner, but not explicitly called out as a banner item (ex: uswds-init.js items)
• Searched closed PRs in both the USWDS and USWDS-Site repo for the word "banner"
• Collected all found change items from 2.7.0 and above

Outstanding questions

• How far back do we go?
• Do we include beta release items? Is everything accounted for in the major release notes?

Tasks completed

• Updated PR descriptions to include release notes/instructions for handling breaking changes (ex: summary section in https://github.com/uswds/uswds/pull/4695)
• Updated naming of changelog data keys
• Added banner changelog data

Next tasks:

Update guidelines for PRs:

• All PRs for both repos should have the component name in the title.
• All USWDS PRs should explicitly state if the change is breaking and if so, provide clear instructions for user actions to remediate.

Testing and review

This is an early phase review. At this point I am looking for feedback according to the comment below.

So if you are curious, poke around and let me know if you have any questions or comments.

[amyleadem]

@thisisdano @mejiaj @bonnieAcameron @jaclinec

I have added a first pass at the banner changelog mockup, and was hoping to get early feedback on UX and data construction before I get too far down the road.

In this PR, I have added real data for every change item I could find for banner, going as far back as 2.7.0. Choosing 2.7.0 has no inherent meaning, it just felt like a good point to check in and ask how far back we wanted to go.

Additionally, I have updated the data structure here according to the notes recorded in issue 1787. I imagine that initial review of this PR might lead to changes in the data structure and that these topics will continue to evolve.

So at this phase, I was hoping to get feedback on if this structure is providing the optimal user and developer experience and also get guidance on how far back we should be going for data collection.

If we affirm that this data structure and presentation meet our needs, I will go back through and confirm the data for every change item and make sure nothing was missed.

[jaclinec]

@amyleadem This looks great to me - seems clear and laid out in a way that is easily scannable with the right amount of detail. I had one question. Are we still including a column for 'Type' of change - i.e. code or guidance? I did not see that in the preview.

[amyleadem]

Updated 10/27 - edited to reflect new key names

@thisisdano @mejiaj @mahoneycm I have made the following updates to the data structure.

• Flattened the data structure
  • Created summary and ~moreSummary~ additional_info fields.
• Removed pageURL and added ~pageType~ type in an effort to reduce redundant data and the reliance on explicit pathing.
  • Example: if title: Accordion and type: Component, we should be able to build a path to components/accordion if we ever need it.
  • type will also allow us to create more specific collections of changelog data if we ever desire it
  • Note: It will be trickier to create paths to nested pages like: https://designsystem.digital.gov/documentation/getting-started/developers/phase-one-install/, but I am thinking we can just provide explicit paths only for these more rare occurrences if needed.
  • Open to suggestions for the Standard Values on this field.
• Created component-template.yml, which contains inline comments that can be the basis for our data files.
  • If we like this inline comment option, I can either rework or remove the changelog-readme file.

[amyleadem]

@thisisdano cc: @mejiaj Per our discussion yesterday, here are some proposed additional data fields:

title:
type:
changelogURL:
items:
  - date:
    summary:
    additional_info:
-   isCodeUpdate:
+   affectsAccessibility:
+   affectsAssets:
+   affectsGuidance:
+   affectsJavascript:
+   affectsMarkup:
+   affectsStyles:
    isBreaking:
    pr:
    repo:
    version:

The list is somewhat lengthy, but these switches would only needed to be included in the data if their value is true. The additional fields will give us flexibility in the future to not only filter by change type, but combining this with the isBreaking field can give us enhanced flexibility for letting users know if additional action is required. For example:

• If isBreaking is true, we can choose to inform users that an update is Required
• If affectsMarkup or affectsAssets is true and isBreaking is false, we can inform users that an update is Recommended
• If affectsStyles or affectsJavascript is true and isBreaking is false, we can inform users that no additional action is needed.
• Additionally, affectsAccessibility can be used as a flag for mandatory action. So if affectsAccessibility and affectsMarkup are both true and isBreaking is false, we could still choose to let users know that action is Required.

Let me know if this is in line with your thinking and if you have any suggestions or questions.

Once we decide on our keys, I will update the files and docs.

[amyleadem]

@mejiaj From my understanding at least, the main motivation for adding these keys is that one of the main questions users might have when looking at a changelog is: "Do I need to take any additional action here?"

We identify breaking changes, but we don't really mark when things like markup or assets should or must be changed (for reasons other than breaking - e.g. accessibility).

Initially, we considered a simple field like userActionNeeded, but realized that we could instead infer this data if we identified more change types and combined them with isBreaking. The affects fields also have the added benefit of providing us with useful data that will allow us to display and filter change items by type in collected changelogs. Additionally, it also could give us more flexibility to even redefine user action needs in the future.

As far as timing, it felt simpler to identify these fields while we are doing initial data entry, rather than needing to cycle back through everything later.

As far as data structure goes, I am not sure I see a difference in the actual dev ease of use in either structure, but I could just be thinking too narrowly. My only slight style lean is that it might reduce entry error if each item had its own line and was a simple boolean. Definitely open to a different structure, so I am happy to defer.

I hope that answers your questions!

[thisisdano]

I've updated the keys for better consistency across themes.

• Used lowercase values for type (Component → component)
• Removed isCodeUpdate since it's redundant with new affects keys
• additional_info → summaryAdditional
• pr → githubPr
• repo → githubRepo
• version → versionUswds (there may be versionPackage in the future)
• Changed isBreaking to a bool for simplicity. Cases where we think there is a potential breaking change should be treated as a breaking change (true).
• Added the following keys to indicate the scope or domain of the change. This is meant to help users understand what part of the code changed in each entry.
  • affectsAccessibility
  • affectsMarkup
  • affectsJavascript
  • affectsStyles
  • affectsContent
  • affectsGuidance
  • affectsAssets

Key	Description	Optional	Value type	Standard values	Displayed
title	Page title	no	string	N/A	No
type	Identify page type	no	string	component, documentation, pattern, template, token, utility	No
changelogURL	url for CHANGELOG.MD	yes	string	N/A	Yes
date	Merge date	no	date	N/A	Yes
summary	Short description of change	no	string	N/A	Yes
summaryAdditional	Additional description	yes	string	N/A	Yes
isBreaking	Breaking change	no	boolean	true, false	Yes
affectsAccessibility	Change affects accessibility	yes	boolean	true, false	yes
affectsMarkup	Change affects component markup	yes	boolean	true, false	yes
affectsJavascript	Change affects component JS	yes	boolean	true, false	yes
affectsStyles	Change affects component styles, appearance, or settings	yes	boolean	true, false	yes
affectsContent	Change affects content in the component itself	yes	boolean	true, false	yes
affectsGuidance	Change affects component guidance	yes	boolean	true, false	yes
affectsAssets	Change affects assets related to a component, like images	yes	boolean	true, false	yes
githubPr	Pull request number	no	number	N/A	Yes
githubRepo	Pull request repo name	no	string	uswds, uswds-site	Yes
versionUswds	USWDS Version Number	no	number	N/A	Yes

[thisisdano]

I've also made a couple presentational changes.

• Separated the github link from the description for legibility
• Added an Affects column
• Highlighted breaking changes with a red tag
• Highlighted accessibility changes with a gold tag

[amyleadem]

@thisisdano I was able to get the site to build. It was getting confused about the value of changelogURL, but commenting out the blank data fields resolved the issue.

Additionally, I removed the comments on the blank items in the component .yml files because after doing some preliminary data entry today, it was much simpler to move forward without the comments. I believe we can rely on _component-template.yml instead as our guide for entry.

All in all, I think the data setup looks great and we should be ready to start migrating data.

For the display, I did want to flag that the content in the table display gets a bit - wobbly - at tablet widths. I think we can probably clear that up with some min-widths or alternate display for these widths. I will look into solutions tomorrow. This shouldn't be a blocker for migration.

[amyleadem]

@thisisdano @mejiaj I committed a proposed solution for the table display. d38522c

Proposal:

This commit does the following:

• At medium widths:
  • Moves the Breaking flag to the description cell
  • Hides the date
• At any width:
  • Shrinks mono font from 2xs to 3xs
  • Replaces .flex classes with .grid-col

Narrow:

Medium:

Wide:

Let me know if you have feedback!

[amyleadem]

@thisisdano @mejiaj I merged this work into al-changelog-main to create a central hub into which we can merge all subsequent data and code revisions. From this point on, we should branch all changes off of (and merge into) al-changelog-main.

Additionally:

• Opened issue #1869 to track the fix for the table presentation at tablet widths.
• Drafted PR https://github.com/uswds/uswds-site/pull/1870 to more easily view changes in al-changelog-main

Please let me know if you have any questions.