From 9739db8d06ac62ea8442cfc394fc4dce3ac7612d Mon Sep 17 00:00:00 2001 From: James Mejia Date: Fri, 22 Mar 2024 09:40:05 -0500 Subject: [PATCH 1/3] Add staying up-to-date note. Closes #90 --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a6795c1..4e24b35 100644 --- a/README.md +++ b/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 @@ -146,6 +146,7 @@ With that setup, you could do the following in the terminal: - **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. - **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. +- **Staying up-to-date with USWDS.** When updating your project's version of USWDS; code won't be copied over until you run the `npx gulp update` command. You can see all of the required changes available on the [USWDS releases](https://github.com/uswds/uswds/releases) page. ### Updating the USWDS icon sprite From d5893442306ebda268eb014381c8851fe28f7842 Mon Sep 17 00:00:00 2001 From: James Mejia Date: Fri, 22 Mar 2024 10:24:07 -0500 Subject: [PATCH 2/3] Rename update task and note on staying up-to-date --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4e24b35..410e7bd 100644 --- a/README.md +++ b/README.md @@ -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,15 +138,14 @@ 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. +- **Staying up-to-date with USWDS.** When updating your project's version of USWDS; code won't be copied over until you run the `npx gulp updateUswds` command. You can see all of the required changes available on the [USWDS releases](https://github.com/uswds/uswds/releases) page. Alternatively, you can run the `copyAssets` task. This task updates static assets (like images, fonts, and compiled JavaScript) only and you don't risk clobbering your customizations. - **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. -- **Staying up-to-date with USWDS.** When updating your project's version of USWDS; code won't be copied over until you run the `npx gulp update` command. You can see all of the required changes available on the [USWDS releases](https://github.com/uswds/uswds/releases) page. ### Updating the USWDS icon sprite From 0875046da2c8353c08a324476aec2606e6fcf462 Mon Sep 17 00:00:00 2001 From: James Mejia Date: Fri, 22 Mar 2024 10:59:50 -0500 Subject: [PATCH 3/3] Update README.md Co-authored-by: Amy Leadem <93996430+amyleadem@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 410e7bd..f83dc02 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,7 @@ With that setup, you could do the following in the terminal: ### 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. -- **Staying up-to-date with USWDS.** When updating your project's version of USWDS; code won't be copied over until you run the `npx gulp updateUswds` command. You can see all of the required changes available on the [USWDS releases](https://github.com/uswds/uswds/releases) page. Alternatively, you can run 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.