USWDS-Site - Content: Add note about incorrect package date to download page

[mahoneycm]

Summary

Added site note to download page addressing incorrect package dates.

Important

We are adding another note to the Documentation page which is generated by USWDS README content. This work is being addressed in uswds/uswds#5871

Related issue

Closes #2499

Related pull requests

uswds/uswds#5871

Preview link

Preview link →

Problem statement

NPM purposefully sets package dates to 10/26/1985 to ensure hash-identical tarballs no matter when or on what device the npm pack is ran. This can confuse users who inspect the package and see the incorrect files for the date.

Solution

Add note to site to specify this is intended behavior from NPM.

Testing and review

1. Visit download page
2. Confirm note is showing
3. Confirm there are no grammatical errors
4. Confirm note is styled appropriately
5. Approve of changelog file and display

Tip

There is a slight indentation on the version and hash numbers. If we want the note to match this style, I can add the link-download-subtext class, or similar margin utility class

[mejiaj]

Thanks for creating the note. I'd like to see if we can do a plain language pass.

Essentially, the date isn't what users are expecting and this is expected because of how the code is package and shipped.

[finekatie]

commented in thread

[amyleadem]

@mahoneycm Is the intention to have the same note in both the README and the download page? If so, I wonder if we can pull in the README content onto the download page so that we don't have to do dual maintenance if we ever need to update the copy.

We should be able to isolate the note in the README by using split, like we do on the documentation page.

Do you see any disadvantages to this approach?

[sarah-sch]

LGTM

[mejiaj]

Can we try Amy's idea in comment to re-use content and avoid having to maintain it in multiple places?

[finekatie]

LGTM. I don't know (technically) about the solution Amy proposed, but if it allows us to publish once and display in multiple places, that's great.

[mahoneycm]

Using liquid split to isolate note from USWDS README

After testing, it unfortunately doesn't seem possible to isolate the note form the USWDS readme without adding additional HTML or by adding a very specific slice feature to slice the note using the character count of the section.

In the Documentation page we are able to split the content between two heading elements that are created via markup. Since there is no markup that we can use to exclusively target the note.

Further, even with the following HTML, it proved difficult to isolate the note markup without causing visual regressions.

Example:

<div id="npm-note"> <!-- Used to target the note with `split`. Cannot use p class due to it being removed during split -->
  <p class="site-note">
    <strong>Note:</strong> Files in the downloadable USWDS package will show a "last modified" date of October 26, 1985. This is <a href="https://github.com/npm/npm/issues/20439#issuecomment-385121133">intentional</a>. This default date is set by npm on all its packages to ensure builds will be identical.
  </p>
</div>

Important

Since we were unable to maintain this information in one location, I added a comment to ensure these notes match across repos

[amyleadem]

Looks good to me! Confirmed it matches the text in uswds/uswds#5871. Thanks for adding those comments.

[mejiaj]

Approved with minor suggestion.

[amyleadem]

@mahoneycm Can you create a changelog entry for this change?

[amyleadem]

Also, just flagging that the base branch for this is main. I am not sure if we wanted it to be merged with other 3.8.1 changes in the release-3.8.1 branch. Just flagging for consideration.

[mahoneycm]

Changelog

I created a new changelog for the download page and this update! I opted to name this as about-download since it lives in the "How to use USWDS" section of the site.

[mahoneycm]

Important

Changelog date should be updated before merge

[thisisdano]

Merging over pa11y crashes