USWDS-Site - USWDS 3.0 Migration Page #1529
Conversation
I updated lead text to reflect new content guidance. Upon release of 3.0, devs will need to update all three links on this page (1 for the new code and 2 for new design assets). The version number under the "code" heading needs to be updated to "3.0." The text of both links under the "design assets" heading each need to be updated: –to reference the new version number –to reflect the new file size of the assets
I've revised the summary text under "Developers," "Designers," and "USWDS project wiki." As we prepare for the release of 3.0, the following issue is outstanding: From this page, we link to our project wiki, in which v1 is referenced under current initiatives. We should remove this link (at least temporarily, though maybe permanently since we aren't updating this content and it's weird it's presented the same as our user guidance). If we keep the link, we should update the wiki.
Revised to clarify 3.0 does not support IE11.
Revised so the notice box references v 3 instead of 2. The following is an outstanding issue on/related to this page: –Under "USWDS for designers" we need to provide downloads for the new assets. The downloads for the old assets need to be moved to appear under "Retired design files." –In the second paragraph under "USWDS for designers," we link to a GitHub repo. This repo has, what I assume to be a change log that will need to be updated to reflect any changes in 3.0.
-Small change in line 80 to reflect new instructions. -Please also review Step 4 table for path information to ensure there should be no changes.
-Line 134 change from IE in example to Firefox
Line 29 Update from USWDS 2 to USWDS 3
Line 70: Updated file import path
|
Notes:
|
|
I also see that the "menu" at the top of the page doesn't align with the content any longer. I think we've removed "update to USWDS Compile" and it should probably be instead (as Matt suggested in the doc):
SUMMARY OF REQUESTED CHANGES:
|
|
OK, I'm going to be working on this today — thanks for your work getting it built out! |
3.0 Migration guide - convert accordion to markdown
Co-authored-by: Amy Leadem <93996430+amyleadem@users.noreply.github.com>
Co-authored-by: Amy Leadem <93996430+amyleadem@users.noreply.github.com>
pages/documentation/migration-V3.md
Outdated
| <li>Search for a line like <strong>const USWDS = "node_modules/uswds/dist"</strong> in your Gulp setup. This indicates that you're using the Gulp setup we distributed as USWDS Gulp.</li> | ||
| <li> | ||
| Update the USWDS <strong>const</strong> to the updated uswds package location | ||
| <p><strong>Old</strong></p> | ||
| <code>const USWDS = "node_modules/uswds/dist";</code> | ||
| <p><strong>New</strong></p> | ||
| <code>const USWDS = "node_modules/@uswds/uswds";</code> | ||
| <br> | ||
| </li> | ||
| <li> | ||
| Search for <strong>includePaths</strong> in your project's Gulp files. The paths in this list are where the Sass compiler looks for your source files. In USWDS 3.0 | ||
| <p><strong>Old</strong></p> | ||
| <pre><code>.pipe( | ||
| sass({ | ||
| includePaths: [ | ||
| PROJECT_SASS_SRC, | ||
| `${USWDS}/scss`, | ||
| `${USWDS}/scss/packages`, | ||
| ], | ||
| }) | ||
| )</code></pre> | ||
| <p><strong>New</strong></p> | ||
| <pre><code>.pipe( | ||
| sass({ | ||
| includePaths: [ | ||
| PROJECT_SASS_SRC, | ||
| `${USWDS}, | ||
| `${USWDS}/packages`, | ||
| ], | ||
| }) | ||
| )</code></pre> | ||
| </li> | ||
| <li>Recompile your Sass as usual. When it compiles, it is now using USWDS 3.0!</li> | ||
| </ol> |
There was a problem hiding this comment.
Expanding on my earlier comment first made here.
I did a fresh install of USWDS Gulp on a test project and found the instructions didn't match the current standard USWDS Gulp references. Working on the assumption that many users will be using the defaults from USWDS Gulp, I updated the instructions in this section.
@mejiaj @thisisdano can you confirm that these updates are required/advisable?
Additionally, is the +/- diff a clear way to communicate the changes?
.site-terminal styles. If either of these techniques are problematic, please let me know. I am very open to suggestions.
Snapshot from federalist:
Code update:
- Search for a line like
const uswds = require("./node_modules/uswds-gulp/config/uswds");orconst uswds = "node_modules/uswds/dist"in your Gulp setup. This indicates that you're using the Gulp setup we distributed as USWDS Gulp. - Update the USWDS
constelements to the updated USWDS package location:
- const pkg = require("./node_modules/uswds/package.json");
+ const pkg = require("./node_modules/@uswds/uswds/package.json"); - const uswds = require("./node_modules/uswds-gulp/config/uswds");
+ const uswds = "node_modules/@uswds/uswds";-
Search for references to
${uswds}in theincludePathsandgulp.src()found in your project’s Gulp files. These paths tell the Sass compiler where to look for USWDS source files.Some of our file directories have moved in USWDS 3.0, and it is necessary to point Gulp to the correct location inside
node_modules/@uswds/uswds. Below are snippets from the standard USWDS Gulp references and their necessary updates:... - gulp.src(`${uswds}/scss/theme/**/**`) + gulp.src(`${uswds}/dist/theme/**/**`) ... - gulp.src(`${uswds}/fonts/**/**`) + gulp.src(`${uswds}/dist/fonts/**/**`) ... - gulp.src(`${uswds}/img/**/**`) + gulp.src(`${uswds}/dist/img/**/**`) ... - gulp.src(`${uswds}/js/**/**`) + gulp.src(`${uswds}/dist/js/**/**`) ... includePaths: [ PROJECT_SASS_SRC, - `${uswds}/scss`, + `${uswds}/dist/scss`, - `${uswds}/scss/packages`, + `${uswds}/packages`, ],
-
Recompile your Sass as usual and check that your files compiled as expected. When it compiles successfully, it is now using USWDS 3.0!
pages/documentation/migration-V3.md
Outdated
|
|
||
| {:.site-terminal} | ||
| ```js | ||
| /* gulpfile.js */ | ||
|
|
||
| const uswds = require("@uswds/compile"); | ||
|
|
||
| /** | ||
| * USWDS version | ||
| */ | ||
|
|
||
| uswds.settings.version = 3; | ||
| ``` |
There was a problem hiding this comment.
@thisisdano @mejiaj Here's a first pass for USWDS compile. Working on standardizing the instruction format to match USWDS Gulp
- Search for
const uswds = require("@uswds/compile");in your Gulp setup. This indicates that you're using the Gulp setup we distributed as USWDS Compile. - Update your
gulpfile.jsto file to includeuswds.settings.version = 3;. This setting manages the default USWDS source paths and will point Gulp to the new USWDS 3.0 package locations./* gulpfile.js */ const uswds = require("@uswds/compile"); /** * USWDS version */ uswds.settings.version = 3;
- Recompile your Sass as usual and check that your files compiled as expected. When it compiles successfully, it is now using USWDS 3.0!
Co-authored-by: Amy Leadem <93996430+amyleadem@users.noreply.github.com>
Preview
USWDS 3.0 Migration →
Description
Creates USWDS 3.0 migration guide based on this mockup
Because of having to use the
usa-accordioncomponent as well as code blocks with strikethrough, HTML syntax is used throughout the markdownAdditional information
Heading Level 4 tags appear in all caps
Heading level 3 on top, Heading level 4 below
Before you hit Submit, make sure you’ve done whichever of these applies to you:
npm testand make sure the tests for the files you have changed have passed.