Merge branch 'develop' of https://github.com/uswds/uswds-compile into…

… al-pr-template

.snyk

@@ -0,0 +1,30 @@
+# Snyk (https://snyk.io) policy file, patches or ignores known vulnerabilities.
+version: v1.25.0
+# ignores vulnerabilities until expiry date; change duration by modifying expiry date
+ignore:
+  SNYK-JS-INFLIGHT-6095116:
+    - '*':
+        reason: No available upgrade or patch
+        expires: 2024-06-19T14:39:21.242Z
+        created: 2024-05-20T14:39:21.251Z
+  SNYK-JS-ANSIREGEX-1583908:
+    - '*':
+        reason: Upgrading Gulp causes regression in asset compilation
+        expires: 2024-06-21T14:02:31.969Z
+        created: 2024-05-22T14:02:31.974Z
+  SNYK-JS-BRACES-6838727:
+    - '*':
+        reason: No available upgrade or patch
+        expires: 2024-06-19T14:38:10.435Z
+        created: 2024-05-20T14:38:10.440Z
+  SNYK-JS-MICROMATCH-6838728:
+    - '*':
+        reason: No available upgrade or patch
+        expires: 2024-06-19T14:39:37.460Z
+        created: 2024-05-20T14:39:37.466Z
+  SNYK-JS-POSTCSS-5926692:
+    - '*':
+        reason: No available upgrade or patch
+        expires: 2024-06-19T14:39:55.905Z
+        created: 2024-05-20T14:39:55.911Z
+patch: {}

README.md

@@ -28,7 +28,7 @@ npm install @uswds/compile --save-dev
 
 ### Gulpfile setup
 
-Create a file called `gulpfile.js` at the root of your project (or use an existing Gulpfile if one already exists). It needs to do the following
+Create a file called `gulpfile.js` at the root of your project (or use an existing Gulpfile if one already exists). It needs to do the following:
 
 - Import the `@uswds/compile` package
 - Set any project settings
@@ -129,7 +129,7 @@ For example, if you have the following `gulpfile.js`:
 exports.compile = uswds.compile;
 exports.watch = uswds.watch;
 exports.init = uswds.init;
-exports.update = uswds.updateUswds;
+exports.updateUswds = uswds.updateUswds;
 exports.default = uswds.watch;
 ```
 
@@ -138,12 +138,12 @@ With that setup, you could do the following in the terminal:
 - **Compile Sass:** `npx gulp compile` or `npx gulp`
 - **Watch for changes and recompile:** `npx gulp watch`
 - **Initialize a new project:** `npx gulp init`
-- **Update USWDS static assets and recompile:** `npx gulp update`
+- **Update USWDS static assets and recompile:** `npx gulp updateUswds`
 
 ### Usage tips
 
 - **Use `init` only once.** The `init` task is meant for initializing the design system on a project. Since it will overwrite project files (like settings files and the Sass entry point), use it sparingly and don't use it for updating the design system on a project, or at any point after you've customized your settings files.
-- **Update USWDS assets with `copyAssets`.** Don't update assets with `init`, use the `copyAssets` task. This task updates static assets (like images, fonts, and compiled JavaScript) only and you don't risk clobbering your customizations.
+- **Stay up-to-date with USWDS with `updateUswds`.** When updating your project's version of USWDS, run the `npx gulp updateUswds` command to copy any updated USWDS assets into your project. Alternatively, you can run the `copyAssets` task. These tasks update USWDS static assets (like images, fonts, and compiled JavaScript) and will not override any of your project customizations. These actions might introduce breaking changes, so be sure to check out the related [USWDS releases notes](https://github.com/uswds/uswds/releases) for any additional tasks that must be completed when updating to a new version of USWDS. 
 - **Compile only from a single Sass entry point.** Define the location of this entry point with `paths.dist.theme`. If you have project Sass files outside the `paths.dist.theme` directory, load these files into your single entry point via `@forward`, `@use`, or `@import`. To include these project Sass files in your `gulp watch` task, set `paths.src.projectSass` to your project Sass directory. The Sass will still compile from the single entry point located in `paths.dist.theme`.
 - **Only check theme files and custom icons into version control.** You should have a build process that copies static assets like images, fonts, and compiled JavaScript from the `uswds` package. This assures that these assets are up-to-date with whatever version of USWDS you're using. You only need to track your customizations (like settings, theme files, custom icons, and your gulpfile) in version control.