USWDS - README: Add note about incorrect package link to download page #5871
Conversation
README.md
Outdated
| @@ -214,6 +214,7 @@ If you’re using a framework or package manager that doesn’t support npm, you | |||
|
|
|||
| You'll notice in our example above that we also outline a `stylesheets`, `images` and `javascript` folder in your `assets` folder. These folders are to help organize any assets that are unique to your project and separate from the design system assets. | |||
|
|
|||
| **Note:** The file date defaults to October 26, 1985, when you download and install this package. This is intentional. NPM sets a default date to ensure reproducible builds for npm packages. | |||
There was a problem hiding this comment.
For clarity, does this only happen everywhere (NPM, GitHub, Website) or just a specific instance?
There was a problem hiding this comment.
It looks like installing the uswds package using npm will show the last modified date of the current date and time.
This is related solely to the .tgz compressed package
There was a problem hiding this comment.
I think the placement of the note in the "Downloading the package from github" and the new wording is enough specificity to now add any additional instruction.
"Files in the downloadable USWDS package..."
Would love to hear your thoughts on if we need to specify further!
There was a problem hiding this comment.
@mahoneycm
Thanks for setting this up. I added a few questions in the comments below. Let me know if you have any questions!
Also, what do you think about adding this to 3.8.1?
README.md
Outdated
| @@ -214,6 +214,7 @@ If you’re using a framework or package manager that doesn’t support npm, you | |||
|
|
|||
| You'll notice in our example above that we also outline a `stylesheets`, `images` and `javascript` folder in your `assets` folder. These folders are to help organize any assets that are unique to your project and separate from the design system assets. | |||
|
|
|||
| **Note:** The file date defaults to October 26, 1985, when you download and install this package. This is intentional. NPM sets a default date to ensure reproducible builds for npm packages. | |||
There was a problem hiding this comment.
In the PR description, you mentioned that this note would receive the site-note class. Was it intentionally left off here? Ultimately it depends on how much attention we want on this note, but I lean towards highlighting it with site-note just because the documentation page is so gray otherwise and it would be good to call out notes.
There was a problem hiding this comment.
Sorry, originally it had the site-note class. I was under the impression that the readme would be generated without the {:.site-note} liquid block but I was mistaken. I added a note to the testing instructions but forgot to remove it from the summary
I was unable to add the site-note class without it appearing incorrectly in the readme. Opted to match other notes on that page by bolding the
Note:span.
There was a problem hiding this comment.
I don't know why I hadn't considered... I am able to add HTML syntax and accomplish this
<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>Testing for regression now
There was a problem hiding this comment.
Alright I was able to get this working! Let me know if you have any issues with implementing this way!
There was a problem hiding this comment.
Reverted this change after @mejiaj mentioned not using HTML within markdown if possible
We should avoid HTML inside of markdown if possible. We just want the content.
There was a problem hiding this comment.
Looks good to me! Confirmed it matches the text in uswds/uswds-site#2621
Summary
Added note to the USWDS README. This will also update the Documentation page on site.
Note
I used HTML instead of standard markdown here in order to utilize thesite-noteclass for the website rendered version of this information:This change was reverted to avoid using HTML within markup
Note now displays on site without the note styles
Breaking change
This is not a breaking change.
Related issue
Closes #5872
Related pull requests
uswds/uswds-site#2621
Preview link
Rich content README →
Demo site with documentation preview →
Tip
The demo repo pulls in the readme data of this branch in the site _config.yml [INSERT LINK] file.
I was required to run
rm -rf .jekyll_get_cacheto clear the jekyll cache and get the documentation page to update.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 packis 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
site-noteclass without it appearing incorrectly in the readme. Opted to match other notes on that page by bolding theNote:span.npmdecision dates.Additional context
I added a link to the npm decision on dates that is captured in a GitHub issue. This appears to be the best source of truth for this information. I was unable to find any documentation on their website addressing this concern.