From ca23d914139c7667b71344a236919b55d697a280 Mon Sep 17 00:00:00 2001 From: Maxx Crawford Date: Mon, 9 Aug 2021 11:33:27 -0500 Subject: [PATCH 1/8] Update README, add coding standards doc --- README.md | 27 +++++++++++++-------------- docs/coding-standards.md | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 14 deletions(-) create mode 100644 docs/coding-standards.md diff --git a/README.md b/README.md index 217e14dcb7..16d389a24e 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,9 @@ with other data to personally identify, track, and/or [target them](https://www.facebook.com/business/help/606443329504150?helpref=faq_content). ## Development + +Please refer to our [coding standards](docs/coding-standards.md) information for code styles, naming conventions and other methodologies. + ### Requirements * python 3.7 (suggest using [virtualenv](https://docs.python-guide.org/dev/virtualenvs/)) @@ -19,7 +22,9 @@ them](https://www.facebook.com/business/help/606443329504150?helpref=faq_content * On OSX: `brew install postgresql libpq` * On Fedora: `sudo dnf install libpq-devel` * [SES](https://aws.amazon.com/ses/) if you want to send real emails -* [NPM](https://www.npmjs.com/) and [Gulp](https://gulpjs.com/) to compile SCSS +* [Node 12.X](https://nodejs.org/en/download/) – Needed for front-end SCSS compiling + * [NPM](https://www.npmjs.com/) + * [Gulp](https://gulpjs.com/) to compile SCSS ### Install and Run the Site Locally 1. Clone and change to the directory: @@ -36,7 +41,7 @@ them](https://www.facebook.com/business/help/606443329504150?helpref=faq_content source env/bin/activate ``` -3. Install Pyhton and Node requirements: +3. Install Python and Node requirements: ```sh pip install -r requirements.txt @@ -80,7 +85,7 @@ them](https://www.facebook.com/business/help/606443329504150?helpref=faq_content Next you'll need to enable Firefox Accounts auth ... -#### Enable Firefox Accounts Auth +#### Recommended: Enabel Firefox Accounts authentication To enable Firefox Accounts authentication on your local server, you can use the "private-relay (local)" OAuth app on oauth-stable.dev.lcip.org. @@ -107,21 +112,15 @@ Now you can sign into [http://127.0.0.1:8000/](http://127.0.0.1:8000/) with an FxA. Remember: you'll need to use an account on oauth-stable.dev.lcip.org, not the production accounts.firefox.com. -#### Enable SES -TODO - - -### Install and run the add-on locally + -The add-on adds Firefox UI to generate and auto-fill email addresses. You may -want to build the add-on so that it communicates with your `127.0.0.1:8000` -server instead of the production `relay.firefox.com` server: -1. In the `extension/` directory, run `npm install` and then `npm run build` +#### Optional: Install and run the add-on locally -2. Use `about:debugging` to install the resulting `static/downloads/addon/latest/private_relay.zip` file. - * Note: A link to the `.zip` is also available at http://127.0.0.1:8000/accounts/profile/ +*Note: The add-on is located in a [seperate repo](https://github.com/mozilla/fx-private-relay-add-on/). See it for additional information on getting started.* +The add-on adds Firefox UI to generate and auto-fill email addresses across the web. Running the add-on locally allows it to communicate with your local server (`127.0.0.1:8000`) instead of the production server (`relay.firefox.com`). ## Production Environments diff --git a/docs/coding-standards.md b/docs/coding-standards.md new file mode 100644 index 0000000000..3d60717106 --- /dev/null +++ b/docs/coding-standards.md @@ -0,0 +1,38 @@ +# Coding Standards + +### Lint styles + +For JavaScript, we follow [ESLint's recommended rules](https://eslint.org/docs/rules/). + +For SCSS and CSS, we follow [the standard configuration](https://github.com/stylelint/stylelint-config-standard). + +## Protocol Integration + +We leverage the Protocol [design system](https://protocol.mozilla.org/docs/glossary.html) and framework. See additional documentation on Protocol at https://protocol.mozilla.org/docs. + +### Class Naming Convention + +For ease of integration and to avoid conflicts with other sites, frameworks, and libraries, most classes in Protocol are prefixed with our global namespace `.mzp-` for “Mozilla Protocol”. If the style is custom/outside of Protocol, we drop the `.mzp` prefix. + +We follow a [SMACSS-based naming convention](http://smacss.com/book/categorizing) with a set of prefixes to put rules into a few different categories: + +- `c-` for component names. Expect a lot of this one, e.g. `.mzp-c-card`, `.mzp-c-button`. +- `t-` for theme styles, when a component has one or more alternative styles, e.g. `.mzp-t-dark`, `.mzp-t-product-firefox`. +- `l-` for layout-related styles, e.g. `.mzp-l-content`, `.mzp-l-grid-third`. These are essentially presentational names, mostly used for container elements. +- `u-` for utility styles, which have a broad scope and can be powerful overrides, e.g. `.mzp-u-inline`, `.mzp-u-title-md`. These are presentational so should be rare. Prefer mixins in a style sheet over classes in HTML. +- `is-` to indicate a current state, e.g. `.mzp-is-active`, `.mzp-is-collapsed` (typically assigned by JS and not hard-coded). +- `has-` to indicate that a component contains some other component, when the parent gets some styling to accommodate the child, e.g. `.mzp-has-submenu`, `.mzp-has-image`. +- `js-` used as a behavior hook for JavaScript, e.g. `.mzp-js-sticky`, `.mzp-js-collapsible`, `.mzp-js-toggle`. Indicates potential for a change of state and usually shouldn’t have any styling. +- `a- `for CSS animation names, e.g. `.mzp-a-fade-in`, `.mzp-a-slide-from-right`. + +Our names are all lowercase and hyphen-separated or “kebab-case,” e.g. `.mzp-c-card`, `.mzp-c-card-title`. This brings with it the potential for long kebabs of multipart, hyphenated names. Names should be as short as possible and as long as necessary. Clarity is key. If we find our names getting obscenely long and confusing we may need to revise our convention but we’re trying it this way first. + +### CSS Coding Guide + +We follow [Protocol's CSS coding guide](https://protocol.mozilla.org/docs/css-guide.html). See their documentation for additional details. + +- Use [simple selectors](https://protocol.mozilla.org/docs/css-guide.html#simple-selectors) +- Use [minimal nesting](https://protocol.mozilla.org/docs/css-guide.html#minimal-nesting) +- [Format](https://protocol.mozilla.org/docs/css-guide.html#format) your CSS +- Use `//` for [comments](https://protocol.mozilla.org/docs/css-guide.html#comments) in Sass instead of `/* */` +- Use the [right unit](https://protocol.mozilla.org/docs/css-guide.html#units) for the right context. \ No newline at end of file From 4b9861c693b967995d148118a3ed73e149b8b92d Mon Sep 17 00:00:00 2001 From: Maxx Crawford Date: Mon, 9 Aug 2021 11:37:32 -0500 Subject: [PATCH 2/8] Updated social app config to a table --- README.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 16d389a24e..254b426d2e 100644 --- a/README.md +++ b/README.md @@ -102,15 +102,19 @@ To do so: page](http://127.0.0.1:8000/admin/socialaccount/socialapp/), sign in with the superuser account you created above, and add a social app for Firefox Accounts: - * Provider: Firefox Accounts - * Name: oauth-stable.dev.lcip.org - * Client id: 9ebfe2c2f9ea3c58 - * Secret key: ping groovecoder for this - * Sites: 127.0.0.1:8000 -> Chosen sites +| Field | Value | +|-------|-------| +| Provider | Firefox Accounts | +| Name | `oauth-stable.dev.lcip.org` | +| Client id | `9ebfe2c2f9ea3c58 ` | +| Secret key | Contact @groovecoder | +| Sites | `127.0.0.1:8000 ` -> Chosen sites | Now you can sign into [http://127.0.0.1:8000/](http://127.0.0.1:8000/) with an -FxA. Remember: you'll need to use an account on oauth-stable.dev.lcip.org, not -the production accounts.firefox.com. +FxA. + +:warning: Remember that you'll need to use an account on oauth-stable.dev.lcip.org, not +the production site, accounts.firefox.com. From 58a1118ed9788510ca240a1ffd0b9a492829e1c2 Mon Sep 17 00:00:00 2001 From: Maxx Crawford Date: Mon, 9 Aug 2021 11:41:50 -0500 Subject: [PATCH 3/8] Additional README fixes --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 254b426d2e..e178182e39 100644 --- a/README.md +++ b/README.md @@ -83,9 +83,7 @@ Please refer to our [coding standards](docs/coding-standards.md) information for python manage.py runserver ``` -Next you'll need to enable Firefox Accounts auth ... - -#### Recommended: Enabel Firefox Accounts authentication +#### Recommended: Enable Firefox Accounts authentication To enable Firefox Accounts authentication on your local server, you can use the "private-relay (local)" OAuth app on oauth-stable.dev.lcip.org. @@ -107,7 +105,7 @@ superuser account you created above, and add a social app for Firefox Accounts: | Provider | Firefox Accounts | | Name | `oauth-stable.dev.lcip.org` | | Client id | `9ebfe2c2f9ea3c58 ` | -| Secret key | Contact @groovecoder | +| Secret key | Request this from [@groovecoder](https://github.com/groovecoder) | | Sites | `127.0.0.1:8000 ` -> Chosen sites | Now you can sign into [http://127.0.0.1:8000/](http://127.0.0.1:8000/) with an @@ -122,7 +120,7 @@ TODO --> #### Optional: Install and run the add-on locally -*Note: The add-on is located in a [seperate repo](https://github.com/mozilla/fx-private-relay-add-on/). See it for additional information on getting started.* +*Note: The add-on is located in a [separate repo](https://github.com/mozilla/fx-private-relay-add-on/). See it for additional information on getting started.* The add-on adds Firefox UI to generate and auto-fill email addresses across the web. Running the add-on locally allows it to communicate with your local server (`127.0.0.1:8000`) instead of the production server (`relay.firefox.com`). From be904950997722816c93c2b1bf2351a4a343eac4 Mon Sep 17 00:00:00 2001 From: Maxx Crawford Date: Mon, 9 Aug 2021 11:43:45 -0500 Subject: [PATCH 4/8] Add stylelint config --- docs/coding-standards.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/coding-standards.md b/docs/coding-standards.md index 3d60717106..fbccc93a19 100644 --- a/docs/coding-standards.md +++ b/docs/coding-standards.md @@ -4,7 +4,7 @@ For JavaScript, we follow [ESLint's recommended rules](https://eslint.org/docs/rules/). -For SCSS and CSS, we follow [the standard configuration](https://github.com/stylelint/stylelint-config-standard). +For SCSS and CSS, we follow [the standard configuration](https://github.com/stylelint/stylelint-config-standard) with a few exceptions noted in the [StyleLint config file](https://github.com/mozilla/fx-private-relay/blob/main/.stylelintrc.json). ## Protocol Integration From 119e5250c576b00fdc310df00a8fad3b787465c8 Mon Sep 17 00:00:00 2001 From: Maxx Crawford Date: Mon, 9 Aug 2021 14:19:21 -0500 Subject: [PATCH 5/8] README: Stage OAuth Fix Co-authored-by: luke crouch --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e178182e39..6058a860c2 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ Please refer to our [coding standards](docs/coding-standards.md) information for #### Recommended: Enable Firefox Accounts authentication To enable Firefox Accounts authentication on your local server, you can use the -"private-relay (local)" OAuth app on oauth-stable.dev.lcip.org. +"Firefox Private Relay local dev" OAuth app on accounts.stage.mozaws.net. To do so: From f3d3a3d72fcabd97038070b4baf7a771de75a830 Mon Sep 17 00:00:00 2001 From: Maxx Crawford Date: Mon, 9 Aug 2021 14:19:26 -0500 Subject: [PATCH 6/8] README: Stage OAuth Fix Co-authored-by: luke crouch --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6058a860c2..50f5fe9e89 100644 --- a/README.md +++ b/README.md @@ -103,7 +103,7 @@ superuser account you created above, and add a social app for Firefox Accounts: | Field | Value | |-------|-------| | Provider | Firefox Accounts | -| Name | `oauth-stable.dev.lcip.org` | +| Name | `accounts.stage.mozaws.net` | | Client id | `9ebfe2c2f9ea3c58 ` | | Secret key | Request this from [@groovecoder](https://github.com/groovecoder) | | Sites | `127.0.0.1:8000 ` -> Chosen sites | From 7215feb660e2c2fbf81c7646875f6e5cba372550 Mon Sep 17 00:00:00 2001 From: Maxx Crawford Date: Mon, 9 Aug 2021 14:19:38 -0500 Subject: [PATCH 7/8] README: Update team contact point. Co-authored-by: luke crouch --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 50f5fe9e89..d042fbed8e 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ superuser account you created above, and add a social app for Firefox Accounts: | Provider | Firefox Accounts | | Name | `accounts.stage.mozaws.net` | | Client id | `9ebfe2c2f9ea3c58 ` | -| Secret key | Request this from [@groovecoder](https://github.com/groovecoder) | +| Secret key | Request this from `#fx-private-relay-eng` Slack channel | | Sites | `127.0.0.1:8000 ` -> Chosen sites | Now you can sign into [http://127.0.0.1:8000/](http://127.0.0.1:8000/) with an From c6badf0e08547454c2843353b544bd304ad3ba56 Mon Sep 17 00:00:00 2001 From: Maxx Crawford Date: Mon, 9 Aug 2021 14:19:47 -0500 Subject: [PATCH 8/8] README: Stage OAuth Fix Co-authored-by: luke crouch --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d042fbed8e..90d5a6d28e 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,7 @@ superuser account you created above, and add a social app for Firefox Accounts: Now you can sign into [http://127.0.0.1:8000/](http://127.0.0.1:8000/) with an FxA. -:warning: Remember that you'll need to use an account on oauth-stable.dev.lcip.org, not +:warning: Remember that you'll need to use an account on https://accounts.stage.mozaws.net/, not the production site, accounts.firefox.com.