[Demo] USWDS-Site: Changelog prototype

[amyleadem]

:warning: Note: This is an early-phase prototype, designed to be a tool to begin conversation. This should not to be merged in its current state.

Related issue

Related to https://github.com/uswds/uswds-site/issues/1280

Preview link

Preview links:

• Accessibility page
• Accordion page

Problem statement

Users should be able to easily find relevant updates that have been made to our guidance and code. However, we currently do not have a mechanism for visibly tracking change on our guidance website.

Solution

Adding a "Latest updates" section that lists relevant changes will give users the ability to easily find what has been updated along with a timeline for change.

Implementation

Add a "Latest updates" section at the bottom of the page that includes:

• A list of items of meaningful changes. Each of these list items should include:
  • The date the change was merged
  • A brief description of the change
    • From the Changelog template PR:

    Whenever possible, change items should:
        - Include a brief description of the update that focuses on user benefit
        - Use a consistent set of verbs to begin each statement.
            - Examples: "Fixed", "Added", "Improved", "Optimized", "Updated" at the start of the summary helps indicate change type
        - Use plain language and be human-readable.
    

  • A link to the related PR
• For component pages, also include:
  • A link to the component's CHANGELOG.md file (when available)
  • Indication if this is a breaking change
  • link to related release/version

What updates to include

• Any code changes that require user action
• Meaningful updates to guidance that may or may not require user action
• Any change to visual appearance
• Any change to behavior or functionality

What updates to exclude

• Non-meaningful updates to typos, punctuation and grammar
• Code enhancements that do not require user action

Testing and review

This is an early phase of this prototype. If we move forward with this method, the code will be rewritten to be more easily maintained. All feedback is welcome.

---

Before opening this PR, make sure you’ve done whichever of these applies to you:

• [ ] Confirm that this code follows the 18F Front End Coding Style Guide and Accessibility Guide.
• [ ] Run git pull origin [base branch] to pull in the most recent updates from your base and check for merge conflicts. (Often, the base branch is develop).
• [ ] Run npm run prettier:scss to format code.
• [ ] Run npm test and confirm that all tests pass.
• [ ] Run your code through HTML_CodeSniffer and make sure it’s error free.

[jaclinec]

This looks great! My feedback for this proto is similar to the feedback I left for #207. I'd add a line for rationale/research to back up our recommendation where applicable.

[amyleadem]

Some next steps identified during the team discussion:

• [ ] Improve summary copy
  • Current copy limits list scope - can we more accurately communicate will be included in the list of on-page updates?
• [ ] Figure out how to approach the data structure for changelog items
  • Correct data structure could give us flexibility for different ways to collate later
• [x] Investigate alternate visual presentation --> pursue possible table layout
• [x] Include related version number on each item
• [x] Update guidance to include items that are functional improvements/enhancements
  • We can communicate when components improve, even if there is no related user action
• [x] Demonstrate appearance of breaking changes
• [x] Add latest updates to sidenav

Questions remaining:

• Will this be a 1:1 for items in component changelog.md?
• What is the correct approach to data? Do individual .yml files for each page work or should we investigate another approach?

[amyleadem]

@thisisdano @mejiaj @bonnieAcameron @jaclinec I have made some updates to the content and visual presentation of the on-page changelog prototypes, as well as did some initial data structuring. I am interested to hear feedback.

Content structure/Visual updates

1. Updated the on-page prototype to display as a table rather than a list.
   • In these prototypes, different page types display different table content. Specifically, guidance pages will not have the "Version" and "Breaking" columns that the component pages will have.
2. Updated the summary a bit to widen the scope of what will be included in the on-page changelog.
   • Note: This prototype assumes that there will NOT be a 1:1 match for content in the CHANGELOG.md file. If we decide instead to match the CHANGELOG.md, we can probably safely remove the summary and link to the changelog file from this section.

There are also some potentially out-of-scope content ideas that are kinda sorta related to changelogs that I wanted to throw out there. I am mostly interested in assessing if these are items we want to include in the Changelog effort:

1. Added a place to put the current version number in the Package section
2. Added a contribute section at the end to act as a call to action for users to engage/update. This was inspired by @bonnieAcameron flagging the Edit button on digital.gov.

Curious to hear your opinions -

• Is the table the best format for this information?
• Do we like the column content?
• Are all of the elements there that we need?
• Does it cover all possible use cases?

Data

I also did a first pass at a possible yaml-based data structure. At this phase, I consider this to be a possible path for MVP while while we work through the transition to component packages. It also gives us a way to create changelog items for guidance pages.

The hope is that we can figure out a path that does not require dual maintenance for component changelogs, but I wanted to nail down the UX for each format before we dug deeper into that. (If you want to prioritize data structure first instead, please let me know).

Thoughts on this approach?

Demos

I have added a couple of active demos and some screenshots for reference. Interested in your thoughts!

Guidance page demo - Accessibility page This version hides the link to the changelog, and removes the version number and breaking changes columns.

Component page demo - Accordion page

[jaclinec]

I think this looks really good and I like the table format. It's easy to scan and is written in plain language. I like the column categories and can't think of anything to suggest.

[amyleadem]

Post-discussion notes:

• Change date format to YYYY-MM-DD
• Demonstrate the transition from USWDS version to package version
• Consider collating everything into a collected changelog

[amyleadem]

Closing in favor of https://github.com/uswds/uswds-site/pull/1789, which builds on this PR and now has more content.