USWDS-Compile - Sass: Create quiet deprecations setting

[mahoneycm]

Summary

Silences Sass deprecation warnings for downstream users while allowing local failures to still be triggered.

USWDS Sass deprecations are being tracked in uswds/uswds#6104

Based on work contributed by @mdmower-csnw. Thank you for your contribution!

Breaking change

This is not a breaking change.

Related issue

Closes #132

Related pull requests

Follow up to #126 and additional Sass deprecations popping up.

Documentation update: uswds/uswds-site#3006

Preview link

Test repo →

Problem statement

In its next major release, Sass is changing how it handles mixed declaration style definitions to match new CSS patterns. Because of this, users are getting alarming warnings during compilation.

The pattern is not currently deprecated and we are on track to update the related USWDS code.

Sass continues to push out new deprecation warnings in minor releases.

Solution

In gulpfile.js, create sassSilenceDeps setting and set the default to true.

This approach will mute USWDS warnings, including any future warnings that come up, while allowing warnings from custom sass to still be triggered in the terminal.

This will allow users to be made aware of impending deprecations without worrying about our own.

Users can decide to turn on the deprecation warning if they would like additional context on the upcoming deprecations.

Major changes

• New setting: uswds.settings.compile.quietSassDeps set to true by default.
• Users will no longer be notified of the upcoming Sass deprecations we are on track to fix.
• Users will still be notified of deprecations related to custom Sass that they will be responsible for updating.

Testing and review

1. Confirm USWDS deprecations are silenced

1. On Sandbox main branch, install this version of compile

   npm install "https://github.com/uswds/uswds-compile/tree/cm-quietDeps-setting" --save-dev

2. Run npm run uswds:buildSass

3. Confirm there are no deprecation warnings

2. Confirm quietSassDeps setting is respected

1. After completing the steps above, visit gulpfile.js

2. Under line 15 add the following:

   uswds.settings.compile.quietSassDeps = false;

3. Run npm run uswds:buildSass

4. Confirm deprecation now warnings appear in terminal

3. Confirm custom sass triggers deprecation warnings

1. Checkout Sandbox testing repo locally
2. Run npm install
3. Run npm run uswds:buildSass
4. Confirm the deprecation warnings appear
5. Confirm they all point to _uswds-custom-styles.scss
6. Confirm there are no USWDS deprecation messages

[mlloydbixal]

This works great! Love that it won't need further updates for future deps and it honors custom warnings.

LGTM! 👍

[mejiaj]

@mahoneycm I tested all three use cases you outlined. Confirming that this work fixes those use cases.

There was a little confusion in the first test case.

[mahoneycm]

@mejiaj to for clarirty, are you seeing deprecation warnings on the main branch immediately after installing this working branch?

In my instructions, I laid it out in three linear sections and marked where you would and would not see deprecation warnings. During my testing, I saw no deprecation warnings in the "1. Confirm USWDS deprecations are silenced" section.

They should only begin to appear at the end of the next section 🤔

[amyleadem]

LGTM! One small suggestion on the text in the README, but other than that, looking good!

• Confirm that this silences USWDS Sass deprecation warnings
• Confirmed project Sass still throws deprecation warnings
• Confirmed Sass still compiles as expected
• Confirmed that the uswds.settings.compile.quietSassDeps setting works as expected
• Confirmed the README is updated and accurate
  • Suggested a small tweak for clarity

Note

I needed to update the uswds branch in the Sandbox testing repo from step 3 to develop since the POAM branch was already merged in.

[amyleadem]

Adding one more suggestion for consideration. After reading through the doc updates, I'm feeling like some added clarity to the setting name might be helpful. Happy to talk about it you have any questions.

[amyleadem]

suggestion: Wondering if we can improve clarity with the setting name here to highlight that this is about Sass "warnings", not just "deps" (This also clarifies that we are talking about deprecations, not dependencies).

Also wondering if it should be written in the negative, so that we can set "false" as a default. This part is very much a quibble and could just be personal preference, but it felt a bit odd to add a settings.compile.quietSassDeps = false to the gulpfile.

Curious what you think!

Suggested change

	quietSassDeps: true
	sassDeprecationWarnings: false

[mahoneycm]

Hmm I'm divided here. While I do think that the naming convention your suggesting makes sense, part of me thinks we should match what Sass is providing. Since quietDeps is the name of setting I see potential value in keeping ours close to it.

Do you see any value in changing it to sassQuietDeps so we're sort of "prefixing" the Sass setting name with "Sass"?

Alternatively, we use this approach which would probably be more readable for users unfamiliar with this Sass deprecation 🤔

sassDeprecationWarnings: false
...
sass({
  ...
  quietDeps: !settings.compile.sassDeprecationWarnings,
})

[mahoneycm]

Renamed in 7a4c434!

[mdmower-csnw]

I don't mean to rock the boat as this is an appreciated feature, but I think it's worth pointing out that there are other open issues that could be solved at the same time by simply allowing users to configure sass options. The approach I took in the fork we're using not only silences deprecations by default (i.e. good out of box experience), but it also:

1. let's users fine-tune their deprecation notice preferences
2. could satisfy USWDS-Compile - Feature: Allow users to define SASS output style #80 if a restriction I put in place is removed
3. (I think) could satisfy USWDS-Compile - Feature: Ability to specify external packages #59 with a bit of effort in handling includes

[mahoneycm]

@mdmower-csnw Thank you for sharing! We've decided to move forward with this approach for the time being but I've opened #133 for further discussion and to track this potential new feature.

We appreciate your input and feedback as we improve Compile!

[cathybaptista]

@mahoneycm just want to confirm... on the 1st test step, I am getting a deprication, although it is different from those I get in step 3. Here is a vid so you can see exactly what I'm talking about. :)

Screen.Recording.2024-12-11.at.4.14.52.PM.mov

[mahoneycm]

@mahoneycm just want to confirm... on the 1st test step, I am getting a deprication, although it is different from those I get in step 3. Here is a vid so you can see exactly what I'm talking about. :)

Good call out @cathybaptista! That deprecation is separate from style definition deprecations and is being tracked by uswds/uswds#6103! We'll resolve that in upcoming work. It's good to know that users may still see that warning despite this PR.

[cathybaptista]

@mahoneycm LGTM then. :)

[amyleadem]

LGTM! Approving because the code looks good, but the PR description needs some updates (listed below).

Thanks for setting up these testing branch and instructions. Made checking everything very straightforward!

• Confirm that this silences USWDS Sass deprecation warnings by default
• Confirmed that the uswds.settings.compile.sassDeprecationWarnings = true turns USWDS deprecation warnings back on
• Confirmed non-USWDS Sass triggers deprecation warnings
• Confirmed Sass still compiles as expected
• Confirmed the README is updated and accurate
• Confirmed the PR description is up-to-date and accurate
  • There are outdated references to settings.compile.quietSassDeps. These should be updated to settings.compile.sassDeprecationWarnings
  • I needed to update the uswds branch in the Sandbox testing repo from step 3 to develop since the POAM branch was already merged in.