1. Download the newest version of uswds via their GitHub: https://github.com/uswds/uswds.
2. Clone the forked uswds-rails repository to your local, if you don't already have it, from the Agile Six GitHub: https://github.com/agilesix/uswds-rails.
3. Branch off of the most recent version branch (2.11.1 as of 04/13/21) and name the branch after the uswds version number.
4. Copy the fonts, images, and scss folder contents from the newly downloaded uswds version and replace the existing folder contents for each of these items within the vendor/assests path. Important note: Be sure to copy the new folder contents into the corresponding uswds folder (ex: copy the fonts folder contents from the new version to the vendor/assets/fonts/uswds folder of the existing version).
   
   
5. Copy the new javascripts/uswds.js file to the existing vendor/assets/javascripts/uswds folder.
   
6. Copy the same scss folder from step 3 to the existing app/assets/stylesheets/uswds folder.
   
7. Rails-ify the asset pipeline in the new scss files by adding asset-url and font-url where required. Refer to this commit if need be: https://github.com/agilesix/uswds-rails/commit/9efc311b7673b6765bc2cf3ab36903658b479ef3.
8. Change, if necessary, the $theme-image-path value in the following files:

• Approximately line 28 of app/assets/stylesheets/uswds/theme/_uswds-theme-general.scss should be "uswds".
• Approximately line 28 of app/assets/stylesheets/uswds/settings/_settings-general.scss should be "uswds" !default.
• Approximately line 28 of vendor/assets/stylesheets/uswds/theme/_uswds-theme-general.scss should be "uswds".
• Approximately line 28 of vendor/assets/stylesheets/uswds/settings/_settings-general.scss should be "uswds" !default.

9. Change, if necessary, the $theme-font-path value in the following files:

• Approximately line 80 of app/assets/stylesheets/uswds/theme/_uswds-theme-typography.scss should be "uswds".
• Approximately line 80 of app/assets/stylesheets/uswds/settings/_settings-typography.scss should be "uswds" !default.
• Approximately line 80 of vendor/assets/stylesheets/uswds/theme/_uswds-theme-typography.scss should be "uswds".
• Approximately line 80 of vendor/assets/stylesheets/uswds/settings/_settings-typography.scss should be "uswds" !default.

10. Add, if necessary, the following code to lines 3-5 of app/assets/stylesheets/uswds/uswds.scss:

// Relative font and image file paths
$font-path:  'uswds';
$image-path: 'uswds';

11. Port over all custom javascript from previous version branches in the agilesix/uswds-rails repository. This will potentially be a running list of branches that have custom changes which have yet to be resolved by USWDS, along with the commit numbers that contain each change, so please add to this when any future changes are made.
    As of 04/13/21:
    • Branch 2.8.1: commits 2e308f7bb3835f917ea556d8f5d03006688096f6, 79b82e18284a94e6a8e083b6fbf022a66df75140, and bc5c729d132ef27ccdcf26bdf6cfac530d92ebeb.
12. Change the uswds version number to match the newest version you want to use in the lib/uswds/rails/version.rb file.
13. Commit these changes and push the new branch to GitHub.
14. Branch off of diffusion-marketplace's master branch and point to the new agilesix/uswds-rails branch you created in step 3 by changing the ref value for the uswds-rails gem in the gemfile (ex: gem 'uswds-rails', github: 'agilesix/uswds-rails', ref: 'abc1234'.
15. Run bundle install.
16. Check for any potential adverse effects of upgrading the uswds version and make sure everything looks and works as expected.
    

If you commit additional changes to the new agilesix/uswds-rails branch, be sure to checkout to the diffusion-marketplace branch you created in step 14 and update the ref value in the gemfile and run bundle install.