diff --git a/docs/developer/README.md b/docs/developer/README.md index 8576306d3..3f2d80af4 100644 --- a/docs/developer/README.md +++ b/docs/developer/README.md @@ -61,3 +61,13 @@ Linters: ```shell docker-compose exec app ./manage.py lint ``` + +## USWDS and styling +We use the U.S. Web Design System (USWDS) for building and styling our applications. Additionally, we utilize the [uswds-compile tool](https://designsystem.digital.gov/documentation/getting-started/developers/phase-two-compile/) from USWDS to compile and package the static assets. +When you run `docker-compose up` the `node` service in the container will begin to watch for changes in the `registrar/assets` folder, and will recompile once any changes are made. +Within the `registrar/assets` folder, the `_theme` folder contains three files initially generated by `uswds-compile`: +1. `_uswds-theme-custom-styles` contains all the custom styles created for this application +2. `_uswds-theme` contains all the custom theme settings (e.g. primary colors, fonts, banner color, etc..) +3. `styles.css` a entry point or index for the styles, forwards all of the other style files used in the project (i.e. the USWDS source code, the settings, and all custom stylesheets). + +You can also compile the sass at any time using `npx gulp compile`. Similarly, you can copy over other static assets (images and javascript files), using `npx gulp copyAssets`. diff --git a/docs/operations/README.md b/docs/operations/README.md index a45d4dd8a..437dba2c0 100644 --- a/docs/operations/README.md +++ b/docs/operations/README.md @@ -36,10 +36,16 @@ Binding the database in `manifest-.json` automatically inserts the # Deploy -We have two environments: `unstable` and `staging`. Developers can deploy locally to unstable whenever they want. However, only our CD service can deploy to `staging`, and it does so on every commit to `main`. This is to ensure that we have a "golden" environment to point to, and can still test things out in an unstable space. To deploy locally to `unstable`: +We have two environments: `unstable` and `staging`. Developers can deploy locally to unstable whenever they want. However, only our CD service can deploy to `staging`, and it does so on every commit to `main`. This is to ensure that we have a "golden" environment to point to, and can still test things out in an unstable space. To deploy locally to `unstable`: ```bash cf target -o cisa-getgov-prototyping -s unstable cf push getgov-unstable -f ops/manifests/manifest-unstable.yaml cf run-task getgov-unstable --command 'python manage.py migrate' --name migrate ``` + + +## Serving static assets +We are using [WhiteNoise](http://whitenoise.evans.io/en/stable/index.html) plugin to serve our static assets on cloud.gov. This plugin is added to the `MIDDLEWARE` list in our apps `settings.py`. + +Note that it’s a good idea to run `collectstatic` locally or in the docker container before pushing files up to `unstable`. This is because `collectstatic` relies on timestamps when deciding to whether to overwrite the existing assets in `/public`. Due the way files are uploaded, the compiled css in the `/assets/css` folder on `unstable` will have a slightly earlier timestamp than the files in `/public/css`, and consequently running `collectstatic` on`unstable` will not update `public/css` as you may expect.