From 8b6e313afedadab9ba6d02483d9760b150a7dfa5 Mon Sep 17 00:00:00 2001 From: Leo McArdle Date: Tue, 26 Apr 2022 09:52:54 +0000 Subject: [PATCH] chore(prettier): update existing markdown files to reflect new rules --- CODE_OF_CONDUCT.md | 9 +- README.md | 172 +++++++------- client/src/banners/README.md | 13 +- client/src/ui/README.md | 44 +++- copy/plus/faq.md | 60 ++--- copy/plus/features/collections.md | 42 ++-- copy/plus/features/notifications.md | 42 ++-- copy/plus/features/offline.md | 31 ++- deployer/README.md | 220 +++++++++--------- deployer/aws-lambda/README.md | 40 ++-- docs/REVIEWING.md | 39 ++-- docs/architecture.md | 43 ++-- docs/conventions.md | 4 +- docs/debugging-sitesearch.md | 16 +- docs/deployments.md | 41 ++-- docs/envvars.md | 149 ++++++------ docs/experiments/0001_site-search-x-cache.md | 5 +- .../0002_language-preferredcookie-before.md | 10 +- docs/google-analytics.md | 37 +-- docs/npm-packaging.md | 73 +++--- docs/npm-releases.md | 59 +++-- docs/popularities.md | 16 +- docs/proxying.md | 48 ++-- docs/signingin.md | 32 +-- docs/spas.md | 8 +- docs/typescript.md | 46 ++-- kumascript/README.md | 7 +- testing/README.md | 68 +++--- .../files/en-us/markdown/tool/h2m/expected.md | 3 +- testing/integration/README.md | 6 +- tool/README.md | 18 +- 31 files changed, 742 insertions(+), 659 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index a0d01badb499..595d0048b254 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,9 +1,12 @@ # Community Participation Guidelines -This repository is governed by Mozilla's code of conduct and etiquette guidelines. -For more details, please read the +This repository is governed by Mozilla's code of conduct and etiquette +guidelines. For more details, please read the [Mozilla Community Participation Guidelines](https://www.mozilla.org/about/governance/policies/participation/). ## How to Report -For more information on how to report violations of the Community Participation Guidelines, please read our [How to Report](https://www.mozilla.org/about/governance/policies/participation/reporting/) page. +For more information on how to report violations of the Community Participation +Guidelines, please read our +[How to Report](https://www.mozilla.org/about/governance/policies/participation/reporting/) +page. diff --git a/README.md b/README.md index 5d598cf7e2fc..b5ef5ba7bddc 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,10 @@ ## Quickstart Development on `yari` involves updating the machinery that renders MDN content -or improving the structure and styling of the MDN UI (e.g. the -styling of the header). If you are more interested in contributing to the MDN -content, you should check out the [content](https://github.com/mdn/content) repo -README instead. +or improving the structure and styling of the MDN UI (e.g. the styling of the +header). If you are more interested in contributing to the MDN content, you +should check out the [content](https://github.com/mdn/content) repo README +instead. Before you can start working with Yari, you need to: @@ -19,12 +19,14 @@ Before you can start working with Yari, you need to: So for now let's make an exception. --> -1. Install [git](https://git-scm.com/), - [Node.js](https://nodejs.org) (>= 12.11.0 and < 17.0.0), and [Yarn 1](https://classic.yarnpkg.com/en/docs/install). +1. Install [git](https://git-scm.com/), [Node.js](https://nodejs.org) (>= + 12.11.0 and < 17.0.0), and + [Yarn 1](https://classic.yarnpkg.com/en/docs/install). 1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) - the MDN [content](https://github.com/mdn/content) and [yari](https://github.com/mdn/yari) - repositories using the Fork button on GitHub. + the MDN [content](https://github.com/mdn/content) and + [yari](https://github.com/mdn/yari) repositories using the Fork button on + GitHub. 1. Clone the forked repositories to your computer using the following commands (replace `[your account]` with the account you forked the repositories to): @@ -32,8 +34,8 @@ Before you can start working with Yari, you need to: git clone https://github.com/[your_account]/content.git git clone https://github.com/[your_account]/yari.git - Take a note of the file path to the location where you've cloned that - repo before moving on. + Take a note of the file path to the location where you've cloned that repo + before moving on. @@ -62,33 +64,36 @@ compiled files; this is "riskier" but faster. `yarn dev` always ensures that everything is up-to-date. The `yarn start` command also starts a server with slightly different behavior — -it doesn't automatically reload when its source code files change, -so use with caution. +it doesn't automatically reload when its source code files change, so use with +caution. See also our [reviewing guide](docs/REVIEWING.md) for information on how to review Yari changes. ### Pull request requirements -Firstly, thank you for your interest in contributing to Yari! -We do have a few requirements when it comes to pull requests: - -1. Please make use of a [feature branch workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow). -2. We prefer if you use the [conventional commits format](https://www.conventionalcommits.org/) - when making pull requests. -3. Lastly, we require that all commits are signed. - Please see the documentation [about signed commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) - and [how to sign yours](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) +Firstly, thank you for your interest in contributing to Yari! We do have a few +requirements when it comes to pull requests: + +1. Please make use of a + [feature branch workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow). +2. We prefer if you use the + [conventional commits format](https://www.conventionalcommits.org/) when + making pull requests. +3. Lastly, we require that all commits are signed. Please see the documentation + [about signed commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) + and + [how to sign yours](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) on GitHub. Thank you for your understanding! We look forward to your contributions. ### How to stay up-to-date -Periodically, the code and the content changes. Make sure you stay -up-to-date with something along the following lines (replace `yari-origin` -with whatever you called [the remote location](https://git-scm.com/docs/git-remote) -of the original yari repo): +Periodically, the code and the content changes. Make sure you stay up-to-date +with something along the following lines (replace `yari-origin` with whatever +you called [the remote location](https://git-scm.com/docs/git-remote) of the +original yari repo): git pull yari-origin main yarn @@ -101,41 +106,43 @@ When you embark on making a change, do it on a new branch, for example All source code is [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/). -For content, see its [license](https://github.com/mdn/content/blob/main/LICENSE.md) -in the [mdn/content repository](https://github.com/mdn/content). +For content, see its +[license](https://github.com/mdn/content/blob/main/LICENSE.md) in the +[mdn/content repository](https://github.com/mdn/content). ## How it works Yari does a number of things, the most important of which is to render and serve the MDN content found in the [content repo](https://github.com/mdn/content). Each document is stored as an `index.md` (recommended) or `index.html` file that -contains metadata presented as YAML [front-matter](https://github.com/mdn/content#fundamental-concepts) -followed by the document source. +contains metadata presented as YAML +[front-matter](https://github.com/mdn/content#fundamental-concepts) followed by +the document source. The builder converts these "source files" into "build files" using a CLI tool -that iterates over the files, builds the HTML, and lastly packages it up -with the front-end code, ready to be served as static files. +that iterates over the files, builds the HTML, and lastly packages it up with +the front-end code, ready to be served as static files. ## Development -The `yarn start` command encapsulates the front-end dev server -(on ) and the `server` (on ). +The `yarn start` command encapsulates the front-end dev server (on +) and the `server` (on ). -All the sub-commands of `yarn start` can be broken down and run individually -if you want to work more rapidly. +All the sub-commands of `yarn start` can be broken down and run individually if +you want to work more rapidly. ### Setting up `$EDITOR` -If you configure an environment variable called `EDITOR`, either on your -system as a whole or in the root `.env` file, it can be used in the development -server to link to sources which, when clicked, open in your preferred -editor/IDE. For example, in the root of the repo you could run: +If you configure an environment variable called `EDITOR`, either on your system +as a whole or in the root `.env` file, it can be used in the development server +to link to sources which, when clicked, open in your preferred editor/IDE. For +example, in the root of the repo you could run: echo 'EDITOR=code' >> .env -Now clicking certain links will open files directly in the currently open -VS Code IDE (replace `code` in the above command with a different text editor -name if needed, e.g. `atom` or whatever). To test it, view any document on +Now clicking certain links will open files directly in the currently open VS +Code IDE (replace `code` in the above command with a different text editor name +if needed, e.g. `atom` or whatever). To test it, view any document on and click the "Open in your editor" button. ### How the server works @@ -147,8 +154,8 @@ The `server` has two main jobs: ### Linting -All JavaScript and TypeScript code needs to be formatted with `prettier` -and it's easy to test this with: +All JavaScript and TypeScript code needs to be formatted with `prettier` and +it's easy to test this with: yarn prettier-check @@ -156,30 +163,28 @@ And conveniently, if you're not even interested in what the flaws were, run: yarn prettier-format -When you ran `yarn` for the first time (`yarn` is an alias for -`yarn install`) it automatically sets up a `git` pre-commit hook that uses -`lint-staged` — a wrapper for `prettier` that checks only the files in the git -commit. +When you ran `yarn` for the first time (`yarn` is an alias for `yarn install`) +it automatically sets up a `git` pre-commit hook that uses `lint-staged` — a +wrapper for `prettier` that checks only the files in the git commit. If you have doubts about formatting, submit your pull request anyway. If you -have formatting flaws, the [pull request checks](https://github.com/features/actions) -should catch it. +have formatting flaws, the +[pull request checks](https://github.com/features/actions) should catch it. ### Upgrading Packages -We maintain the dependencies using `Dependabot` in GitHub but if you want -to manually upgrade them you can use: +We maintain the dependencies using `Dependabot` in GitHub but if you want to +manually upgrade them you can use: yarn upgrade-interactive --latest ### Sharing your dev environment with `ngrok` -[`ngrok`](https://ngrok.com/) allows you to start an HTTP proxy -server from the web into your Yari server. This can be useful for testing -your current build using external tools like BrowserStack, WebPageTest, or -Google Translate, or to simply show a friend what you're up to. Obviously -it'll never be faster than your uplink Internet connection but it should -be fairly feature-complete. +[`ngrok`](https://ngrok.com/) allows you to start an HTTP proxy server from the +web into your Yari server. This can be useful for testing your current build +using external tools like BrowserStack, WebPageTest, or Google Translate, or to +simply show a friend what you're up to. Obviously it'll never be faster than +your uplink Internet connection but it should be fairly feature-complete. 1. [Create in account on Ngrok.com](https://dashboard.ngrok.com/signup) 2. [Download the executable](https://ngrok.com/download) @@ -223,36 +228,36 @@ Every `index.html` becomes two files: ### Flaw checks -When building you can enable specific "flaw checks" and their level of -handling. Some flaws are "cosmetic" and some are more -severe but they should never block a full build. +When building you can enable specific "flaw checks" and their level of handling. +Some flaws are "cosmetic" and some are more severe but they should never block a +full build. More information about how to set flaws can be found in `docs/envvars.md`. -Essentially, the default is to _warn_ about any flaw and you can see -those flaws when using . For completed builds, -all flaws are ignored. This makes the build faster and there's also -no good place to display the flaws in a production-grade build. +Essentially, the default is to _warn_ about any flaw and you can see those flaws +when using . For completed builds, all flaws are ignored. +This makes the build faster and there's also no good place to display the flaws +in a production-grade build. -**In the future**, we might make the default flaw level `error` instead. -That means that any new edits to (or creation of) any document will break -in continuous integration if there's a single flaw and the onus will -be on you to fix it. +**In the future**, we might make the default flaw level `error` instead. That +means that any new edits to (or creation of) any document will break in +continuous integration if there's a single flaw and the onus will be on you to +fix it. ## Icons and logos -The various formats and sizes of the favicon are generated -from the file `mdn-web-docs.svg` in the repository root. This file is then -converted to favicons using [realfavicongenerator.net](https://realfavicongenerator.net/). -To generate new favicons, edit or replace the `mdn-web-docs.svg` file -and then re-upload that to realfavicongenerator.net. +The various formats and sizes of the favicon are generated from the file +`mdn-web-docs.svg` in the repository root. This file is then converted to +favicons using [realfavicongenerator.net](https://realfavicongenerator.net/). To +generate new favicons, edit or replace the `mdn-web-docs.svg` file and then +re-upload that to realfavicongenerator.net. ## Contact -If you want to talk to us, ask questions, and find out more, join the -discussion on the -[MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) -on [Matrix](https://wiki.mozilla.org/Matrix). +If you want to talk to us, ask questions, and find out more, join the discussion +on the +[MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on +[Matrix](https://wiki.mozilla.org/Matrix). ## Troubleshooting @@ -262,7 +267,8 @@ Some common issues and how to resolve them. There are two options to resolve this. -1. Disable the watcher via [`REACT_APP_NO_WATCHER`](docs/envvars.md#react_app_no_watcher) +1. Disable the watcher via + [`REACT_APP_NO_WATCHER`](docs/envvars.md#react_app_no_watcher) `echo REACT_APP_NO_WATCHER=true >> .env` @@ -271,8 +277,8 @@ There are two options to resolve this. ### `Error: Cannot find module 'levenary'` -We can't know for sure what's causing this error but speculate a bug in how `yarn` -fails to resolve if certain `@babel` helper libs should install its own +We can't know for sure what's causing this error but speculate a bug in how +`yarn` fails to resolve if certain `@babel` helper libs should install its own sub-dependencies. A sure way to solve it is to run: rm -fr node_modules @@ -280,7 +286,7 @@ sub-dependencies. A sure way to solve it is to run: ### `Error: listen EADDRINUSE: address already in use :::5042` -The default server port `:5042` might be in use by another process. To resolve this, -you can pick any unused port (e.g., 6000) and run the following: +The default server port `:5042` might be in use by another process. To resolve +this, you can pick any unused port (e.g., 6000) and run the following: echo SERVER_PORT=6000 >> .env diff --git a/client/src/banners/README.md b/client/src/banners/README.md index 0f5a91235a40..bb32cbcc88d4 100644 --- a/client/src/banners/README.md +++ b/client/src/banners/README.md @@ -1,6 +1,7 @@ # Using banners -Your first step is to define an `id` for the banner or reuse one of the previous banners' (if appropriate) `ids` in `client/src/banners/ids.ts`. For example: +Your first step is to define an `id` for the banner or reuse one of the previous +banners' (if appropriate) `ids` in `client/src/banners/ids.ts`. For example: ```js export const REDESIGN_ANNOUNCEMENT = "redesign_announcement"; @@ -12,7 +13,8 @@ Next go into `client/src/banners/index.tsx` and import your banner id: import { REDESIGN_ANNOUNCEMENT } from "./ids"; ``` -> NOTE: If there are currently no banners running, ensure that you set `hasActiveBanners` to `true`. +> NOTE: If there are currently no banners running, ensure that you set +> `hasActiveBanners` to `true`. In the `Banner` function update the following code as appropriate: @@ -31,9 +33,12 @@ if (CRUD_MODE || !isEmbargoed(REDESIGN_ANNOUNCEMENT)) { } ``` -> NOTE: The seconds parameter to the `setEmbargoed` function is the number of days to embargo the banner. A banner will always show if you have `REACT_APP_CRUD_MODE` set to `true` in `.env` or the banner is not embargoed. +> NOTE: The seconds parameter to the `setEmbargoed` function is the number of +> days to embargo the banner. A banner will always show if you have +> `REACT_APP_CRUD_MODE` set to `true` in `.env` or the banner is not embargoed. -Now head over to `client/src/banners/active-banner.tsx` and update the following function as appropriate: +Now head over to `client/src/banners/active-banner.tsx` and update the following +function as appropriate: ```js function RedesignAnnouncementBanner({ diff --git a/client/src/ui/README.md b/client/src/ui/README.md index 8dc0ffa48eea..757415721dbc 100644 --- a/client/src/ui/README.md +++ b/client/src/ui/README.md @@ -1,6 +1,7 @@ # The UI Folder -> NOTE: This document is a work in progress. If you have any questions please contact me(@schalkneethling) on Slack +> NOTE: This document is a work in progress. If you have any questions please +> contact me(@schalkneethling) on Slack The UI folder contains all the UI components of the application. @@ -9,29 +10,50 @@ The UI folder contains all the UI components of the application. The most important pieces to understand here is that: - Small concrete components like a button, goes into the `atoms` folder -- As soon as you combine more that one `atom`, it goes into the `molecules` folder -- As soon as you start combining `molecules`, it goes into the `organisms` folder +- As soon as you combine more that one `atom`, it goes into the `molecules` + folder +- As soon as you start combining `molecules`, it goes into the `organisms` + folder -Larger pieces like full pages, will go into the relevant top level folders such as the `client/src/plus/` folder. +Larger pieces like full pages, will go into the relevant top level folders such +as the `client/src/plus/` folder. ## The `minimalist` folder -This is a not in sync copy of [mdn-minimalist](https://github.com/mdn/mdn-minimalist). See the note on the status of this under the `theme` folder docs below. +This is a not in sync copy of +[mdn-minimalist](https://github.com/mdn/mdn-minimalist). See the note on the +status of this under the `theme` folder docs below. ## Style Dictionary -We use [Style Dictionary](https://amzn.github.io/style-dictionary/#/) to build out our first level variables into SASS. Down the road we may want to also generate these same into variables in JS, or for specific mobile platforms. We therefore started down this road now, so that we have the infrastructure in place. +We use [Style Dictionary](https://amzn.github.io/style-dictionary/#/) to build +out our first level variables into SASS. Down the road we may want to also +generate these same into variables in JS, or for specific mobile platforms. We +therefore started down this road now, so that we have the infrastructure in +place. -The variables defined here are hardly ever directly used but, are instead mapped to more second level semantic named that are then used to in components. The source from which Style Dictionary builds are located in `client/src/ui/style-dictionary/`. The config for Style Dictionary is in `sd-config.json` at the root of the project. +The variables defined here are hardly ever directly used but, are instead mapped +to more second level semantic named that are then used to in components. The +source from which Style Dictionary builds are located in +`client/src/ui/style-dictionary/`. The config for Style Dictionary is in +`sd-config.json` at the root of the project. -Tokens directly exported from Figma are located in `client/src/ui/style-dictionary/tokens.json`. This was an initial export which is now manually kept in sync. In future we hope to automate this process. +Tokens directly exported from Figma are located in +`client/src/ui/style-dictionary/tokens.json`. This was an initial export which +is now manually kept in sync. In future we hope to automate this process. ## The `theme` folder -When we embarked on the redesign, the idea was to use [mdn-minimalist](https://github.com/mdn/mdn-minimalist) as the base and override what is different. In the end this prooved more cumbersome than we had hoped. This means that either the `theme` folder will be removed in future or, the `client/src/ui/minimalist` folder. +When we embarked on the redesign, the idea was to use +[mdn-minimalist](https://github.com/mdn/mdn-minimalist) as the base and override +what is different. In the end this prooved more cumbersome than we had hoped. +This means that either the `theme` folder will be removed in future or, the +`client/src/ui/minimalist` folder. -For the moment it is a little confusing 🙃 - If anything is unclear, please reach out. +For the moment it is a little confusing 🙃 - If anything is unclear, please +reach out. ## The `vars` folder -This is the folder into which we will generate the Style Dictionary variables. You should never need to touch these. +This is the folder into which we will generate the Style Dictionary variables. +You should never need to touch these. diff --git a/copy/plus/faq.md b/copy/plus/faq.md index c03fefdec991..a8c663faa177 100644 --- a/copy/plus/faq.md +++ b/copy/plus/faq.md @@ -8,7 +8,8 @@ title: FAQ MDN Plus is a premium subscription service launched in March 2022 by Mozilla. The service allows users to customize their MDN Web Docs experience through -premium features such as [Notifications](/en-US/plus/docs/features/notifications), +premium features such as +[Notifications](/en-US/plus/docs/features/notifications), [Collections](/en-US/plus/docs/features/collections) and [MDN Offline](/en-US/plus/docs/features/offline). @@ -26,15 +27,15 @@ users. A three-tiered pricing model has been put in place in order to try and accommodate our users’ needs as much as possible: -- _MDN Core_ - A free plan, for those ones who want to try out a limited - version of the premium features. +- _MDN Core_ - A free plan, for those ones who want to try out a limited version + of the premium features. - _MDN Plus 5_ - A $5/month or $50/year plan that offers unlimited access to the premium features included in MDN Plus. - _MDN Supporter 10_ - A $10/month or $100/year plan for users who want to - support MDN with a higher amount. On top of the MDN Plus premium features, - MDN supporters will be able to contribute and shape the product moving - forward, by having early access to premium features and a direct feedback - channel with the MDN team. + support MDN with a higher amount. On top of the MDN Plus premium features, MDN + supporters will be able to contribute and shape the product moving forward, by + having early access to premium features and a direct feedback channel with the + MDN team. Subscribing for a yearly plan activates a 20% discount for all the paid options. @@ -53,46 +54,47 @@ as the overall user experience on the website. ## Are we violating any OS license obligation by adding a paid product to MDN? -MDN content is made available under a CC BY-SA 2.5 license. That license -doesn't preclude Mozilla (or other users of MDN content) from having a paid -product. MDN Plus adds premium features like notifications and collections on -top of the free content. Regular users can still access and reuse MDN content -under the Creative Commons license. +MDN content is made available under a CC BY-SA 2.5 license. That license doesn't +preclude Mozilla (or other users of MDN content) from having a paid product. MDN +Plus adds premium features like notifications and collections on top of the free +content. Regular users can still access and reuse MDN content under the Creative +Commons license. ## Where will the money from MDN Plus go? -Since its beginning in 2005, MDN Web Docs has been a project hosted and -provided by Mozilla. Mozilla covers the cost of infrastructure, development -and maintenance of the MDN platform, including a team of engineers and its -own team of dedicated writers. +Since its beginning in 2005, MDN Web Docs has been a project hosted and provided +by Mozilla. Mozilla covers the cost of infrastructure, development and +maintenance of the MDN platform, including a team of engineers and its own team +of dedicated writers. Mozilla wants MDN Plus to help ensure that MDN's open source content continues to be supported into the future. MDN Plus has been built only with Mozilla -resources, and any revenue generated by MDN Plus will stay within Mozilla. -We are looking into ways to reinvest some of these additional funds into open +resources, and any revenue generated by MDN Plus will stay within Mozilla. We +are looking into ways to reinvest some of these additional funds into open source projects contributing to MDN but it is still in the early stages. ## Does the launch of MDN Plus impact the relationship with partners like OWD? The existence of a new subscription model will not detract from MDN's current free Web Docs offering in any way. The current experience of accessing web -documentation will not change for users who do not wish to sign up for a -premium subscription. Open Web Docs (OWD) and Mozilla will continue to work -closely together on MDN for the best possible web platform documentation for -everyone. For more information about how our organizations work together, -please check [this article](https://hacks.mozilla.org/2022/03/mozilla-and-open-web-docs-working-together-on-mdn/). +documentation will not change for users who do not wish to sign up for a premium +subscription. Open Web Docs (OWD) and Mozilla will continue to work closely +together on MDN for the best possible web platform documentation for everyone. +For more information about how our organizations work together, please check +[this article](https://hacks.mozilla.org/2022/03/mozilla-and-open-web-docs-working-together-on-mdn/). ## What regions will MDN Plus be available in? Today, MDN Plus is available in the US and Canada. In the coming months, we are -planning to roll out to other countries including France, Germany, Italy, -Spain, Belgium, Austria, the Netherlands, Ireland, United Kingdom, -Switzerland, Malaysia, New Zealand and Singapore. +planning to roll out to other countries including France, Germany, Italy, Spain, +Belgium, Austria, the Netherlands, Ireland, United Kingdom, Switzerland, +Malaysia, New Zealand and Singapore. ## I have an idea for MDN Plus, who should I contact? In case you have an idea you would like to share about MDN Plus, you can add -your suggestions to our [MDN-feedback](https://github.com/mdn/MDN-feedback) repo. +your suggestions to our [MDN-feedback](https://github.com/mdn/MDN-feedback) +repo. -If a subscriber, you can also leave us feedback by accessing the ‘Feedback’ option -in the user menu. +If a subscriber, you can also leave us feedback by accessing the ‘Feedback’ +option in the user menu. diff --git a/copy/plus/features/collections.md b/copy/plus/features/collections.md index 49eb39115f82..7999d8a3353a 100644 --- a/copy/plus/features/collections.md +++ b/copy/plus/features/collections.md @@ -6,7 +6,11 @@ title: Collections > MDN. Hand _selected_ by you. > -> Collections allow you to save MDN articles and share your library across devices. We also automatically save for you the pages you visit most frequently. They wil help you find what you need quicker by showing first in your search results when looking for a relevant topic and you’ll be able to curate the lists to your liking. +> Collections allow you to save MDN articles and share your library across +> devices. We also automatically save for you the pages you visit most +> frequently. They wil help you find what you need quicker by showing first in +> your search results when looking for a relevant topic and you’ll be able to +> curate the lists to your liking. ## Getting started @@ -43,7 +47,8 @@ You can reach Collections in two ways: ### Mobile -1. Open the main menu by tapping on the **burger menu icon** at the top right of the page. +1. Open the main menu by tapping on the **burger menu icon** at the top right of + the page. ![Screenshot showing the burger menu icon highlighted.](/assets/plus-docs/collections/mobile-burger-menu.png) 2. Tap on **MDN Plus**. ![Screenshot showing the expanded main menu with MDN Plus highlighted.](/assets/plus-docs/collections/mobile-plus-menu.png) @@ -52,7 +57,8 @@ You can reach Collections in two ways: ## The Collections page overview -Your saved articles will appear on the collections dashboard accessible from the **MDN Plus → Collections** link. +Your saved articles will appear on the collections dashboard accessible from the +**MDN Plus → Collections** link. ### Desktop @@ -115,7 +121,8 @@ Remove a saved page from **Collections** 1. Click the **⋮ menu** to the right of the saved page and select **Delete**. ![Screenshot showing the expanded three dots icon. There are two options, the second of which is delete.](/assets/plus-docs/collections/desktop-collections-dashboard-delete.png) -2. Your saved page has now been removed. Select **Undo** in the notification at the bottom of the screen to revert this action. +2. Your saved page has now been removed. Select **Undo** in the notification at + the bottom of the screen to revert this action. ![Screenshot showing the undo toast dialog at the bottom of the page. The undo button located on the right is highlighted](/assets/plus-docs/collections/desktop-collections-undo.png) ### Mobile @@ -133,30 +140,36 @@ Remove a saved page from **Collections** 1. Click the **⋮ menu** to the right of the saved page and select **Delete**. ![Screenshot showing the expanded three dots icon. There are two options, the second of which is delete.](/assets/plus-docs/collections/mobile-collections-dashboard-delete-entry.png) -2. Your saved page has now been removed. Select **Undo** in the notification at the bottom of the screen to revert this action. +2. Your saved page has now been removed. Select **Undo** in the notification at + the bottom of the screen to revert this action. ![Screenshot showing the undo toast dialog at the bottom of the page. The undo button located on the right is highlighted](/assets/plus-docs/collections/mobile-collections-undo.png) ## Filtering saved pages -Saved pages can be filtered by searching Title keywords through the page search bar. +Saved pages can be filtered by searching Title keywords through the page search +bar. ![Screenshot showing collections dashboard highlighting text inside the filter input element.](/assets/plus-docs/collections/desktop-collections-filter.png) ## Sorting saved pages -Saved pages can be sorted by Date added and Title. The input element is located to the right of the Collections search input. +Saved pages can be sorted by Date added and Title. The input element is located +to the right of the Collections search input. ![Screenshot showing collections dashboard with sort element expanded showing the date and title sorting options.](/assets/plus-docs/collections/desktop-collections-sort.png) ## Frequently viewed articles -These are collections we automatically create for you, based on your activity while being logged into MDN Plus. As an MDN Plus user, you are automatically opted into this feature. +These are collections we automatically create for you, based on your activity +while being logged into MDN Plus. As an MDN Plus user, you are automatically +opted into this feature. ![Screenshot showing collections dashboard with the frequently viewed articles tab active.](/assets/plus-docs/collections/desktop-collections-fva.png) ## How are these articles generated? -Frequently viewed pages are articles you visit most frequently while logged into MDN Plus. We will always show you your most recent top viewed 20 pages. +Frequently viewed pages are articles you visit most frequently while logged into +MDN Plus. We will always show you your most recent top viewed 20 pages. ## Remove a saved page from Frequently viewed articles @@ -164,15 +177,18 @@ Frequently viewed pages are articles you visit most frequently while logged into 1. Click the **⋮ menu** to the right of the saved page and select **Delete**. ![Screenshot showing the expanded three dots icon. There are two options, the second of which is delete.](/assets/plus-docs/collections/desktop-collections-delete-fva.png) -2. Your saved page has now been removed. Select **Undo** in the notification at the bottom of the screen to revert this action. +2. Your saved page has now been removed. Select **Undo** in the notification at + the bottom of the screen to revert this action. ![Screenshot showing the undo toast dialog at the bottom of the page. The undo button located on the right is highlighted](/assets/plus-docs/collections/desktop-collections-undo.png) ### Mobile -Click the **⋮ menu** to the right of the saved page and select **Delete**. -Your saved page has now been removed. Select **Undo** in the notification at the bottom of the screen to revert this action. +Click the **⋮ menu** to the right of the saved page and select **Delete**. Your +saved page has now been removed. Select **Undo** in the notification at the +bottom of the screen to revert this action. 1. Click the **⋮ menu** to the right of the saved page and select **Delete**. ![Screenshot showing the expanded three dots icon. There are two options, the second of which is delete.](/assets/plus-docs/collections/desktop-collections-delete-fva.png) -2. Your saved page has now been removed. Select **Undo** in the notification at the bottom of the screen to revert this action. +2. Your saved page has now been removed. Select **Undo** in the notification at + the bottom of the screen to revert this action. ![Screenshot showing the undo toast dialog at the bottom of the page. The undo button located on the right is highlighted](/assets/plus-docs/collections/mobile-collections-fva-undo.png) diff --git a/copy/plus/features/notifications.md b/copy/plus/features/notifications.md index 6e29aa7f7a56..c1cb63057533 100644 --- a/copy/plus/features/notifications.md +++ b/copy/plus/features/notifications.md @@ -4,13 +4,18 @@ title: Notifications # Notifications -> No more surprises: _watch specific pages_ for changes that impact your projects +> No more surprises: _watch specific pages_ for changes that impact your +> projects > -> From tutorial pages to API references, get notifications for the latest developments on MDN. +> From tutorial pages to API references, get notifications for the latest +> developments on MDN. -When you watch a page, MDN Plus sends you notifications for significant events relating to that page. For example, you’ll receive a notification when there’s a major update to the content of the page. +When you watch a page, MDN Plus sends you notifications for significant events +relating to that page. For example, you’ll receive a notification when there’s a +major update to the content of the page. -If a page has a browser compatibility table, then you can subscribe to notifications for web platform feature events such as: +If a page has a browser compatibility table, then you can subscribe to +notifications for web platform feature events such as: - New and upcoming browser support - Removed browser support @@ -19,11 +24,13 @@ If a page has a browser compatibility table, then you can subscribe to notificat ## Getting started -To start getting notifications, **watch** your first page. To do this, visit a page, then click **Watch → Watch page**. +To start getting notifications, **watch** your first page. To do this, visit a +page, then click **Watch → Watch page**. ![Screenshot showing the watch button activated opening a dialog that shows the watch page option.](/assets/plus-docs/notifications/watch-page.png) -When there are notifications, an indicator appears in the user menu on any MDN page or in the notifications list. +When there are notifications, an indicator appears in the user menu on any MDN +page or in the notifications list. ## See what pages you’re watching @@ -33,12 +40,16 @@ You can see what pages you’re watching in two ways: ![Screenshot showing MDN Plus main menu expanded revealing a Notifications menu entry.](/assets/plus-docs/notifications/access-notifications-from-main-menu.png) 2. On the notifications dashboard, click on **Watch list** ![Screenshot showing notifications dashboard with the watch list tab active.](/assets/plus-docs/notifications/watch-list.png) -3. Click on your profile photo in the right corner of your screen and select **Notifications** from the drop-down list. +3. Click on your profile photo in the right corner of your screen and select + **Notifications** from the drop-down list. ![Screenshot showing user menu at the top-right of the page expanded, revealing a notifications menu entry.](/assets/plus-docs/notifications/notifications-user-menu.png) ## Star a notification and review it -If you want to save a notification for later, go to the **Notifications page** and click the **Star** icon next to the notification you want to save. To see a list of starred notifications, go to the **Notifications** page and click **Starred**. +If you want to save a notification for later, go to the **Notifications page** +and click the **Star** icon next to the notification you want to save. To see a +list of starred notifications, go to the **Notifications** page and click +**Starred**. ![Screenshot showing notifications watch list with the star icon highlighted.](/assets/plus-docs/notifications/star-notification.png) @@ -48,15 +59,20 @@ You can **stop watching a page** in two ways: 1. Visit the page you want to stop watching, then click **Watching → Unwatch**. ![Screenshot showing the watch button activated opening a dialog that shows the unwatch option.](/assets/plus-docs/notifications/unwatch-page.png) -2. Go to **Notifications -> Watch list**, and use the **⋮ menu** to the right of the watched page and select **Unwatch**. - Your watched page has now been removed. Select Undo in the notification at the bottom of the screen to revert this action. +2. Go to **Notifications -> Watch list**, and use the **⋮ menu** to the right of + the watched page and select **Unwatch**. Your watched page has now been + removed. Select Undo in the notification at the bottom of the screen to + revert this action. ![Screenshot showing the notifications dashboard with an entries three-dot menu, to the right, activated revealing an unwatch option.](/assets/plus-docs/notifications/unwatch-dashboard.png) -You can also **Bulk unwatch** by checking the box on top of your **Watched list** and then clicking **Unwatch** +You can also **Bulk unwatch** by checking the box on top of your **Watched +list** and then clicking **Unwatch** ![Screenshot showing the notifications dashboard with the bulk unwatch checkbox highlighted.](/assets/plus-docs/notifications/bulk-unwatch-dashboard.png) ## About your notifications inbox -The user menu on MDN pages shows a dot when you have notifications. You can review all of your read, unread, and starred notifications from the notifications list. -Only the most-recent 5,000 notifications are kept in your inbox. Older notifications may be deleted. +The user menu on MDN pages shows a dot when you have notifications. You can +review all of your read, unread, and starred notifications from the +notifications list. Only the most-recent 5,000 notifications are kept in your +inbox. Older notifications may be deleted. diff --git a/copy/plus/features/offline.md b/copy/plus/features/offline.md index 3b5d1939540a..a4afb55c7de2 100644 --- a/copy/plus/features/offline.md +++ b/copy/plus/features/offline.md @@ -6,9 +6,15 @@ title: MDN Offline > _Web docs without web access_: the full power of MDN, offline > -> Leverage the offline capability of our **MDN PWA** to work on the go. Whether you're in a high-speed train, a cabin in the woods or just looking to save some data, MDN Offline gives you access to the full power of your favorite dev resource, so your projects aren't interrupted. The site is snappier and your experience better. +> Leverage the offline capability of our **MDN PWA** to work on the go. Whether +> you're in a high-speed train, a cabin in the woods or just looking to save +> some data, MDN Offline gives you access to the full power of your favorite dev +> resource, so your projects aren't interrupted. The site is snappier and your +> experience better. -When you need access to MDN even without an internet connection, **MDN Offline** allows you to browse the most up to date version of the site, or simply to have a faster experience while saving data. +When you need access to MDN even without an internet connection, **MDN Offline** +allows you to browse the most up to date version of the site, or simply to have +a faster experience while saving data. ## Getting started @@ -19,7 +25,8 @@ To start using MDN Offline, you must first **Enable offline storage**. 2. **Enable offline storage** ![Screenshot showing MDN Offline page with the enable offline toggle highlighted.](/assets/plus-docs/offline/desktop-offline-enable-offline.png) -You can also add it to your homescreen for an experience similar to using a native app. +You can also add it to your homescreen for an experience similar to using a +native app. ## Choose how to stay up-to-date @@ -28,7 +35,8 @@ You can also add it to your homescreen for an experience similar to using a nati 2. Choose how to update 3. Manually update by clicking **Update now** or **Enable auto-update** ![Screenshot showing MDN Offline page with the auto update toggle highlighted.](/assets/plus-docs/offline/desktop-offline-enable-auto-update.png) -4. Clicking **Update now** will start the download of the latest version of MDN Web Docs. +4. Clicking **Update now** will start the download of the latest version of MDN + Web Docs. ![Screenshot showing MDN Offline page with the update now button highlighted.](/assets/plus-docs/offline/desktop-offline-manual-update.png) 5. The date of the last update is also shown. @@ -44,16 +52,21 @@ Some insight into what can be expected from using MDN Offline ### Browsing Content -If offline mode is enabled, offline content is preferred. All content works without an internet connection, with the exception of a few github-based examples and large video files. You can also indicate you prefer offline content even when online. +If offline mode is enabled, offline content is preferred. All content works +without an internet connection, with the exception of a few github-based +examples and large video files. You can also indicate you prefer offline content +even when online. > NOTE: MDN Offline cannot be used while in a private or incognito window. ### Collections -Previously saved pages will appear as such, and you will be able to browse your **Collections**. -However, editing a saved page (adding/removing) does not work without an active internet connection. +Previously saved pages will appear as such, and you will be able to browse your +**Collections**. However, editing a saved page (adding/removing) does not work +without an active internet connection. ### Notifications -Previously received notifications will be displayed and can be read. -However, notifications read while in offline mode will not be marked as read for later, and cannot be starred or deleted without an active internet connection. +Previously received notifications will be displayed and can be read. However, +notifications read while in offline mode will not be marked as read for later, +and cannot be starred or deleted without an active internet connection. diff --git a/deployer/README.md b/deployer/README.md index 6fb44f82d67d..bf18b0c41ab4 100644 --- a/deployer/README.md +++ b/deployer/README.md @@ -1,15 +1,15 @@ # Deployer The Yari Deployer does two things. First, it's used to upload document -redirects, pre-built document pages, static files (e.g. JS, CSS, and -image files), and sitemap files into an existing AWS S3 bucket. Since -we serve MDN document pages from an S3 bucket via a CloudFront CDN, -this is the way we upload a new version of the site. +redirects, pre-built document pages, static files (e.g. JS, CSS, and image +files), and sitemap files into an existing AWS S3 bucket. Since we serve MDN +document pages from an S3 bucket via a CloudFront CDN, this is the way we upload +a new version of the site. Second, it is used to update and publish changes to existing AWS Lambda -functions. For example, we use it to update and publish new versions of -a Lambda function that we use to transform incoming document URL's into -their corresponding S3 keys. +functions. For example, we use it to update and publish new versions of a Lambda +function that we use to transform incoming document URL's into their +corresponding S3 keys. ## Getting started @@ -22,36 +22,37 @@ poetry install poetry run deployer --help ``` -Please refer to the [`boto3` documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#configuration) +Please refer to the +[`boto3` documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#configuration) with regards to configuring AWS access credentials. ## Uploads -The `poetry run deployer upload DIRECTORY` command uploads files as well as redirects -into an existing S3 bucket. Currently, we have three S3 buckets that we -upload into: `mdn-content-dev` (for variations or experimental versions of +The `poetry run deployer upload DIRECTORY` command uploads files as well as +redirects into an existing S3 bucket. Currently, we have three S3 buckets that +we upload into: `mdn-content-dev` (for variations or experimental versions of the site), `mdn-content-stage`, and `mdn-content-prod`. -As input, the `upload` command takes a directory which -contains the files that should be uploaded, but it needs to know where to -find any redirects that should be uploaded as well. By default it searches -for redirects within the content directories specified by `--content-root` -(or `CONTENT_ROOT`) and `--content-translated-root` (or `CONTENT_TRANSLATED_ROOT`). -It does this by searching for `_redirects.txt` files within those directories, -converting each line in a `_redirects.txt` file into an S3 redirect object. -The files and redirects are uploaded into a sub-folder (a.k.a. `prefix`) of the -S3 bucket's root. The prefix (`--prefix` option) defaults to `main`, which is -most likely what you'll want for uploads to the `mdn-content-stage` and -`mdn-content-prod` S3 buckets. However, for uploads to the `mdn-content-dev` -bucket, the prefix is often used to specify a different folder for each -variation of the site that is being reviewed/considered. - -When uploading files (not redirects), the Deployer is intelligent about -what it uploads. If only uploads files whose content has changed, skipping -the rest. However, since the `cache-control` attribute of a file is not -considered part of its content, if you'd like to change the `cache-control` -from what's in S3, it's important to use the `--force-refresh` option to -ensure that all files are uploaded with fresh `cache-control` attributes. +As input, the `upload` command takes a directory which contains the files that +should be uploaded, but it needs to know where to find any redirects that should +be uploaded as well. By default it searches for redirects within the content +directories specified by `--content-root` (or `CONTENT_ROOT`) and +`--content-translated-root` (or `CONTENT_TRANSLATED_ROOT`). It does this by +searching for `_redirects.txt` files within those directories, converting each +line in a `_redirects.txt` file into an S3 redirect object. The files and +redirects are uploaded into a sub-folder (a.k.a. `prefix`) of the S3 bucket's +root. The prefix (`--prefix` option) defaults to `main`, which is most likely +what you'll want for uploads to the `mdn-content-stage` and `mdn-content-prod` +S3 buckets. However, for uploads to the `mdn-content-dev` bucket, the prefix is +often used to specify a different folder for each variation of the site that is +being reviewed/considered. + +When uploading files (not redirects), the Deployer is intelligent about what it +uploads. If only uploads files whose content has changed, skipping the rest. +However, since the `cache-control` attribute of a file is not considered part of +its content, if you'd like to change the `cache-control` from what's in S3, it's +important to use the `--force-refresh` option to ensure that all files are +uploaded with fresh `cache-control` attributes. Redirects are always uploaded. @@ -82,37 +83,36 @@ cd deployer poetry run deployer update-lambda-functions ``` -will discover every folder that contains a Lambda function, create a -deployment package (Zip file) for each one by running: +will discover every folder that contains a Lambda function, create a deployment +package (Zip file) for each one by running: ```sh yarn make-package ``` -and if the deployment package is different from what is already in AWS, -it will upload and publish a new version. +and if the deployment package is different from what is already in AWS, it will +upload and publish a new version. ## Elasticsearch indexing -You just need a URL (or host name) for an Elasticsearch server and the -root of the build directory. The command will trawl all `index.json` files -and extract all metadata and blocks of prose which get their HTML stripped. -The command is: +You just need a URL (or host name) for an Elasticsearch server and the root of +the build directory. The command will trawl all `index.json` files and extract +all metadata and blocks of prose which get their HTML stripped. The command is: ```sh cd deployer poetry run deployer search-index --help ``` -If you have built the whole site (or partially) you simply point to -it with the first argument: +If you have built the whole site (or partially) you simply point to it with the +first argument: ```sh poetry run deployer search-index ../client/build ``` -But by default, it does not specify the Elasticsearch URL/host. You can -either use: +But by default, it does not specify the Elasticsearch URL/host. You can either +use: ```sh export DEPLOYER_ELASTICSEARCH_URL=http://localhost:9200 @@ -126,51 +126,51 @@ poetry run deployer search-index ../client/build --url http://localhost:9200 ``` **Note!** If you don't specify either the environment variable or the `--url` -option, the script will _not_ fail (ie. exit non-zero). -This is to make it convenient in GitHub Actions to control the -execution purely based on the presence of the -environment variable. +option, the script will _not_ fail (ie. exit non-zero). This is to make it +convenient in GitHub Actions to control the execution purely based on the +presence of the environment variable. ### About Elasticsearch aliases -The default behavior is that each day you get a different index name. -E.g. `mdn_docs_20210331093714`. And then there's an alias with a more "generic" name. +The default behavior is that each day you get a different index name. E.g. +`mdn_docs_20210331093714`. And then there's an alias with a more "generic" name. E.g. `mdn_docs`. It's the alias name that Kuma uses to send search queries to. -The way indexing works is that we leave the existing index and its alias in place, -then we fill up a new index and once that works, we atomically "move the alias" and -delete the old index. To demonstrate, consider this example timeline: +The way indexing works is that we leave the existing index and its alias in +place, then we fill up a new index and once that works, we atomically "move the +alias" and delete the old index. To demonstrate, consider this example timeline: -- Yesterday: index `mdn_docs_20210330093714` and `mdn_docs --> mdn_docs_20210330093714` +- Yesterday: index `mdn_docs_20210330093714` and + `mdn_docs --> mdn_docs_20210330093714` - Today: - create new index `mdn_docs_20210331094500` - populate `mdn_docs_20210331094500` (could take a long time) - - atomically re-assign alias `mdn_docs --> mdn_docs_20210331094500` and delete old index `mdn_docs_20210330093714` + - atomically re-assign alias `mdn_docs --> mdn_docs_20210331094500` and delete + old index `mdn_docs_20210330093714` - delete old index `mdn_docs_20210330` -Note, this only applies if you _don't_ use `--update`. -If you use `--update` it will just keep adding to the existing index whose -name is based on today's date. +Note, this only applies if you _don't_ use `--update`. If you use `--update` it +will just keep adding to the existing index whose name is based on today's date. -What this means it that **there is zero downtime for the search queries**. Nothing -needs to be reconfigured on the Kuma side. +What this means it that **there is zero downtime for the search queries**. +Nothing needs to be reconfigured on the Kuma side. ### To update or not start a fresh The default behavior is that it deletes the index first and immediately creates -it again. You can switch this off by using the `--update` option. Then it -will "cake on" the documents. So if something has been deleted since the last -build, you would still have that "stuck" in Elasticsearch. +it again. You can switch this off by using the `--update` option. Then it will +"cake on" the documents. So if something has been deleted since the last build, +you would still have that "stuck" in Elasticsearch. Deleting and re-creating the index is fast so it's relatively safe to use often. -But the indexing can take many seconds and while indexing, Elasticsearch -can only search what's been indexed so far. +But the indexing can take many seconds and while indexing, Elasticsearch can +only search what's been indexed so far. -An interesting pattern would be to use `--update` most of the time and -only from time to time omit it for a fresh new start. +An interesting pattern would be to use `--update` most of the time and only from +time to time omit it for a fresh new start. -But note, if you omit the `--update` (i.e. recreating the index), search -will work. It just may find less that it finds when it's fully indexed. +But note, if you omit the `--update` (i.e. recreating the index), search will +work. It just may find less that it finds when it's fully indexed. ## Analyze PR builds @@ -196,9 +196,10 @@ For example, it will list all external URLs found in the content. ### `--prefix` The `prefix` refers to a prefix in the Deployer upload. I.e. what you set when -you run `poetry run deployer upload --prefix=THIS`. -The `prefix` is used to specify the proper Dev subdomain (`{prefix}.content.dev.mdn.mozit.cloud`) for the URLs of the built documents. For example, -if `--prefix experiment1` is specified, it will list: +you run `poetry run deployer upload --prefix=THIS`. The `prefix` is used to +specify the proper Dev subdomain (`{prefix}.content.dev.mdn.mozit.cloud`) for +the URLs of the built documents. For example, if `--prefix experiment1` is +specified, it will list: ```md ## Preview URLs @@ -211,7 +212,8 @@ Note that this assumes the PR build has been deployed to the Dev server. ### `--repo` -This is useful for debugging when the PR you made wasn't on `mdn/content`. For example: +This is useful for debugging when the PR you made wasn't on `mdn/content`. For +example: ```sh poetry run deployer analyze-pr-build ../client/build --repo peterbe/content ... @@ -219,21 +221,22 @@ poetry run deployer analyze-pr-build ../client/build --repo peterbe/content ... ### `--github-token` -By default it will pick up the `$GITHUB_TOKEN` environment variable but with this -option you can override it. +By default it will pick up the `$GITHUB_TOKEN` environment variable but with +this option you can override it. ### `--pr-number` -This is needed to be able to find the PR (on ) -to post the comment to. +This is needed to be able to find the PR (on +) to post the comment to. ### `--verbose` -This is mostly useful for local development or when debugging. It determines whether -to print to `stdout` what it would post as a PR issue comment. +This is mostly useful for local development or when debugging. It determines +whether to print to `stdout` what it would post as a PR issue comment. -This option, just like the `--dry-run` is technically part of the `deployer` command -and not the `analyze-pr-build` sub-command. So put it before the `analyze-pr-build`. +This option, just like the `--dry-run` is technically part of the `deployer` +command and not the `analyze-pr-build` sub-command. So put it before the +`analyze-pr-build`. ### A complete example @@ -248,16 +251,16 @@ poetry run deployer --verbose --dry-run analyze-pr-build ../client/build \ ## Debugging Analyze PR builds An important part of the `analyze-pr-builds` command is that it must be easy to -debug and develop further without having to rely on landing code in `main` -and seeing how it worked. +debug and develop further without having to rely on landing code in `main` and +seeing how it worked. The first thing you need to do is to download a `build` artifact or to simply -run `yarn build` and use the `../client/build` directory. To download the artifact -go to a finished "PR Test" workflow, -like for +run `yarn build` and use the `../client/build` directory. To download the +artifact go to a finished "PR Test" workflow, like + for example. Near the upper right-hand corner of the content (near the "Re-run jobs" -button) it says "Artifacts (1)". Download that `build.zip` file somewhere and unpack -it. Now you can run: +button) it says "Artifacts (1)". Download that `build.zip` file somewhere and +unpack it. Now you can run: ```sh poetry run deployer --verbose analyze-pr-build ~/Downloads/build ... @@ -270,34 +273,31 @@ You can even go and get a personal access token and set `$GITHUB_TOKEN` The following environment variables are supported. -- `DEPLOYER_BUCKET_NAME` is equivalent to using `--bucket` (the - default is `mdn-content-dev`) -- `DEPLOYER_BUCKET_PREFIX` is equivalent to using `--prefix` (the - default is `main`) -- `DEPLOYER_NO_PROGRESSBAR` is equivalent to using `--no-progressbar` - (the default is `true` if not run from a terminal or the `CI` - environment variable is `true` like it is for GitHub Actions, - otherwise the default is `false`) -- `DEPLOYER_CACHE_CONTROL` can be used to specify the `cache-control` - header for all non-hashed files that are uploaded (the default is - `3600` or one hour) +- `DEPLOYER_BUCKET_NAME` is equivalent to using `--bucket` (the default is + `mdn-content-dev`) +- `DEPLOYER_BUCKET_PREFIX` is equivalent to using `--prefix` (the default is + `main`) +- `DEPLOYER_NO_PROGRESSBAR` is equivalent to using `--no-progressbar` (the + default is `true` if not run from a terminal or the `CI` environment variable + is `true` like it is for GitHub Actions, otherwise the default is `false`) +- `DEPLOYER_CACHE_CONTROL` can be used to specify the `cache-control` header for + all non-hashed files that are uploaded (the default is `3600` or one hour) - `DEPLOYER_HASHED_CACHE_CONTROL` can be used to specify the `cache-control` - header for all hashed files (e.g., `main.3c12da89.chunk.js`) that are - uploaded (the default is `31536000` or one year) -- `DEPLOYER_MAX_WORKERS_PARALLEL_UPLOADS` controls the number of worker - threads used when uploading (the default is `50`) -- `DEPLOYER_LOG_EACH_SUCCESSFUL_UPLOAD` will print successful upload - tasks to `stdout`. The default is that this is `False`. + header for all hashed files (e.g., `main.3c12da89.chunk.js`) that are uploaded + (the default is `31536000` or one year) +- `DEPLOYER_MAX_WORKERS_PARALLEL_UPLOADS` controls the number of worker threads + used when uploading (the default is `50`) +- `DEPLOYER_LOG_EACH_SUCCESSFUL_UPLOAD` will print successful upload tasks to + `stdout`. The default is that this is `False`. - `DEPLOYER_ELASTICSEARCH_URL` used by the `search-index` command. -- `CONTENT_ROOT` is equivalent to using `--content-root` (there is no - default) +- `CONTENT_ROOT` is equivalent to using `--content-root` (there is no default) - `CONTENT_TRANSLATED_ROOT` is equivalent to using `--content-translated-root` (there is no default) ## Contributing -You need to have [`poetry` installed on your system](https://python-poetry.org/docs/). -Now run: +You need to have +[`poetry` installed on your system](https://python-poetry.org/docs/). Now run: ```sh cd deployer @@ -310,8 +310,8 @@ That should have installed the CLI: poetry run deployer --help ``` -If you want to make a PR, make sure it's formatted with `black` and -passes `flake8`. +If you want to make a PR, make sure it's formatted with `black` and passes +`flake8`. You can check that all files are `flake8` fine by running: diff --git a/deployer/aws-lambda/README.md b/deployer/aws-lambda/README.md index 708b8cb39443..36ca7f801786 100644 --- a/deployer/aws-lambda/README.md +++ b/deployer/aws-lambda/README.md @@ -5,12 +5,12 @@ define a unique AWS Lambda function used by Yari. A sub-folder defines an AWS Lambda function if it contains the following: - an `index.js` file containing the code of the Lambda function -- a `package.json` file which defines the Lambda function's dependencies as - well as a `make-package` command that when run creates an AWS Lambda - deployment package (Zip file) containing the function's code (`index.js`) - and dependencies (`node_modules/*`). Also, you'll need to specify the - function's AWS `name` and `region` under the `aws` property within the - `package.json` file (see example below). +- a `package.json` file which defines the Lambda function's dependencies as well + as a `make-package` command that when run creates an AWS Lambda deployment + package (Zip file) containing the function's code (`index.js`) and + dependencies (`node_modules/*`). Also, you'll need to specify the function's + AWS `name` and `region` under the `aws` property within the `package.json` + file (see example below). Here's an example `package.json` file: @@ -45,20 +45,19 @@ cd deployer poetry run deployer update-lambda-functions ``` -will discover every folder that contains a Lambda function, create a -deployment package (Zip file) for each one by running: +will discover every folder that contains a Lambda function, create a deployment +package (Zip file) for each one by running: ```sh yarn make-package ``` -and if the deployment package is different from what is already in AWS, -it will upload and publish a new version. +and if the deployment package is different from what is already in AWS, it will +upload and publish a new version. ## Debugging the `content-origin-request` handler -You can simulate what Lambda@Edge does, but on your laptop. -To start it, run: +You can simulate what Lambda@Edge does, but on your laptop. To start it, run: ```sh cd aws-lambda @@ -67,8 +66,8 @@ yarn install yarn serve ``` -This will start a server at . It's meant to work much -the same as when our Lambda@Edge function is run within AWS. To test it, try: +This will start a server at . It's meant to work much the +same as when our Lambda@Edge function is run within AWS. To test it, try: ```sh curl -I http://localhost:7000/EN-us/docs/Foo/ @@ -79,11 +78,10 @@ But it's a great tool for end-to-end testing our redirect rules. ### An important caveat about `@yari-internals` -The `yarn serve` server will automatically restart itself if a change is -made to the `index.js` or the `server.js` code. -But, if you make an edit to any of the `/libs/**/index.js` files (they're called -`@yari-internal/...` from within the code), then the only way to get them -to become the latest version is to run: +The `yarn serve` server will automatically restart itself if a change is made to +the `index.js` or the `server.js` code. But, if you make an edit to any of the +`/libs/**/index.js` files (they're called `@yari-internal/...` from within the +code), then the only way to get them to become the latest version is to run: ```sh yarn install --force @@ -93,8 +91,8 @@ This is necessary because they're not versioned. ### Headers -All the headers that the Express server receives it replicates. This means you can -test things like this: +All the headers that the Express server receives it replicates. This means you +can test things like this: ```sh curl -I -H 'accept-language: fr' -H 'cookie: preferredlocale=de' http://localhost:7000/docs/Web diff --git a/docs/REVIEWING.md b/docs/REVIEWING.md index 9a5db5a46a78..032262f32b19 100644 --- a/docs/REVIEWING.md +++ b/docs/REVIEWING.md @@ -4,17 +4,18 @@ This document provides information on how to review changes to the Yari repo. ## Before you start -Set up the Yari repo and the corresponding [content repo](https://github.com/mdn/content) -locally, as described in the [Yari quickstart](../README.md#quickstart) guide. Once -you've got them successfully set up, run the `yarn` and `yarn dev` commands to -update your fork with the latest packages and start the MDN test server running -locally on `localhost:3000`. - -`yarn dev` is slower to execute than `yarn start` but it makes sure `client/build/` -is clean, and it also reloads the SSR part of the site (it does a fresh `webpack` -build). This might matter after you've run `git pull` & `yarn`, since certain -packages might be upgraded and it's always good to -test with a clean, up-to-date build. +Set up the Yari repo and the corresponding +[content repo](https://github.com/mdn/content) locally, as described in the +[Yari quickstart](../README.md#quickstart) guide. Once you've got them +successfully set up, run the `yarn` and `yarn dev` commands to update your fork +with the latest packages and start the MDN test server running locally on +`localhost:3000`. + +`yarn dev` is slower to execute than `yarn start` but it makes sure +`client/build/` is clean, and it also reloads the SSR part of the site (it does +a fresh `webpack` build). This might matter after you've run `git pull` & +`yarn`, since certain packages might be upgraded and it's always good to test +with a clean, up-to-date build. Make sure you set the `CONTENT_ROOT` environment variable to an absolute path to the `content` repo `files` subdirectory before running `yarn dev`, so Yari can @@ -47,17 +48,17 @@ When you are tasked with reviewing a Yari pull request: ## Testing KumaScript macro changes -The legacy [KumaScript](https://developer.mozilla.org/en-US/docs/MDN/Tools/KumaScript) +The legacy +[KumaScript](https://developer.mozilla.org/en-US/docs/MDN/Tools/KumaScript) macro system is available inside the yari repo in the [kumascript](https://github.com/mdn/yari/tree/main/kumascript) subdirectory. Testing changes to KumaScript macros — whether you are making your own change or -reviewing someone -else's — is super easy with Yari. Once you have the development server running -as described above, you can load up an MDN page that contains the appropriate -macro call and see if it works. +reviewing someone else's — is super easy with Yari. Once you have the +development server running as described above, you can load up an MDN page that +contains the appropriate macro call and see if it works. If you need to update a macro, you can make a change to the relevant `.ejs` file -(see the [macros](https://github.com/mdn/yari/tree/main/kumascript/macros) subdirectory), -save it, and reload the page in your browser to see the change in action -immediately. +(see the [macros](https://github.com/mdn/yari/tree/main/kumascript/macros) +subdirectory), save it, and reload the page in your browser to see the change in +action immediately. diff --git a/docs/architecture.md b/docs/architecture.md index 7a77e33fabf3..2e940f34407c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -4,18 +4,17 @@ ### Production -This is how we ship the site, as static files served through a CDN with -sensible caching. It allows for viewing and searching through documents.\ -This mode needs to optimize for quick response times and small page sizes and -can do so at the expense of longer build times. +This is how we ship the site, as static files served through a CDN with sensible +caching. It allows for viewing and searching through documents.\ +This mode needs to optimize for quick response times and small page sizes and can +do so at the expense of longer build times. ### Local This is how writers interact with our content. It runs locally on a writer's machine and behaves similarly to production URL structure and appearance.\ -In this mode we optimize for being able to quickly see documents after -starting the server or making changes. We can have larger page sizes as they -are served locally. +In this mode we optimize for being able to quickly see documents after starting the +server or making changes. We can have larger page sizes as they are served locally. ## Modules @@ -26,10 +25,10 @@ them: ### content -Through it you gain access to reading and manipulating our source of truth, -the documents, and their related data like redirects which all are persisted -on disk. It also exports a number of utility functions, needed both internally -and by various other modules.\ +Through it you gain access to reading and manipulating our source of truth, the +documents, and their related data like redirects which all are persisted on +disk. It also exports a number of utility functions, needed both internally and +by various other modules.\ There is no CLI for it and it can only be consumed programmatically. ### import @@ -60,8 +59,8 @@ statically renders it using the **client**'s view code. This module serves two main purposes: -1. An exported function to turn a document from **content** into one that can - be later used by **client** to render out a whole page, which includes +1. An exported function to turn a document from **content** into one that can be + later used by **client** to render out a whole page, which includes **kumascript** rendering, breadcrumb data retrieval and collecting associated flaws. 2. A CLI for rendering out all the requested documents using both the above @@ -69,11 +68,11 @@ This module serves two main purposes: ### server -A server used for development and testing, which simulates how the -static file serving in production would work but also provides local-mode -specific functionalities for modifying content and maintaining a dynamic -_search index_. Instead of serving static files it builds and renders -documents just-in-time when they are requested, using the **build** module. +A server used for development and testing, which simulates how the static file +serving in production would work but also provides local-mode specific +functionalities for modifying content and maintaining a dynamic _search index_. +Instead of serving static files it builds and renders documents just-in-time +when they are requested, using the **build** module. ### testing @@ -82,8 +81,8 @@ viewing, searching and modifying documents. ## Alternatives -Previously we have implemented this with an index of the entire content at -the core of Yari. This had multiple upsides: +Previously we have implemented this with an index of the entire content at the +core of Yari. This had multiple upsides: 1. Lookup of documents did not necessitate them their file path being derivable from their URL. This especially applied to stumptown documents. @@ -94,8 +93,8 @@ the core of Yari. This had multiple upsides: Despite that we decided to go with the architecture outlined above for the following reasons: -1. All the lookups essential to porting MDN content over to Yari can be done - in a reasonable time, without an index, for both production and local-mode. +1. All the lookups essential to porting MDN content over to Yari can be done in + a reasonable time, without an index, for both production and local-mode. 2. Thus, the code complexity introduced through the shared index data structure which also needs to be updated in local-mode, did not justify its existence. 3. While an index is still needed for searching documents and receiving diff --git a/docs/conventions.md b/docs/conventions.md index 89fd92e9c0f6..acea94734ffd 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -11,8 +11,8 @@ which do not adhere to its formatting. - camelCase for everything - except for constants which are all caps snake case (e.g. `CONTENT_ROOT`) -- abbreviations in all caps (e.g. `JSON.parse`, `findByURL`) unless they are - the start of a variable, then it's all lower case (e.g. `let url = 'earl';`) +- abbreviations in all caps (e.g. `JSON.parse`, `findByURL`) unless they are the + start of a variable, then it's all lower case (e.g. `let url = 'earl';`) ## Code Structure diff --git a/docs/debugging-sitesearch.md b/docs/debugging-sitesearch.md index bc4cc0dfc8b0..efe92227747b 100644 --- a/docs/debugging-sitesearch.md +++ b/docs/debugging-sitesearch.md @@ -13,8 +13,8 @@ displaying it in Yari is optional. ## How to enable it -To display each search results `score` and `popularity`, simply add `&debug` -to the current URL. E.g. `?q=foreach&debug` or `?debug=1&q=foreach`. +To display each search results `score` and `popularity`, simply add `&debug` to +the current URL. E.g. `?q=foreach&debug` or `?debug=1&q=foreach`. Now, when you open the `score` and `popularity` is shown. @@ -22,10 +22,10 @@ and `popularity` is shown. ## How to use it You can't affect the sorting algorithm in Yari. To try out different techniques -for the `function_score` in the Python Elasticsearch code, you have to -make changes within Kuma to try different combinations such as `popularity_factor` -and `boost_mode` and `score_mode`. Most of these values are currently hardcoded in -the Kuma Python code. +for the `function_score` in the Python Elasticsearch code, you have to make +changes within Kuma to try different combinations such as `popularity_factor` +and `boost_mode` and `score_mode`. Most of these values are currently hardcoded +in the Kuma Python code. -It's hard to predict exactly what users really prefer and a lot of it depends -on learning from how people react to the sorting. +It's hard to predict exactly what users really prefer and a lot of it depends on +learning from how people react to the sorting. diff --git a/docs/deployments.md b/docs/deployments.md index 0013e4aeb9d0..1483fbc62ebf 100644 --- a/docs/deployments.md +++ b/docs/deployments.md @@ -12,12 +12,13 @@ Prod and stage are supposed to be as similar as possible. All environments are as separate from each other as possible. -You can manually trigger a build for any environment (using the GitHub UI) -but only prod and stage build on a cron job. +You can manually trigger a build for any environment (using the GitHub UI) but +only prod and stage build on a cron job. ## The details -We will try to commit to maintaining the (public) details for each environment in +We will try to commit to maintaining the (public) details for each environment +in [this spreadsheet](https://docs.google.com/spreadsheets/d/1VnnEl-iTtKYmlyN02FiEXygxZCgE4o_ZO8wSleebne4/edit?usp=sharing). But the best source of details are in viewing the 3 GitHub Action workflows: @@ -27,39 +28,39 @@ But the best source of details are in viewing the 3 GitHub Action workflows: 1. `dev-build.yml` Note! Yes, these files are very similar in various tricks and techniques are -blatantly repeated across all three files. But the benefit is that it keeps things -simple for the benefit of security. +blatantly repeated across all three files. But the benefit is that it keeps +things simple for the benefit of security. ## Stage is for testing The stage environment is updated most frequently. Use it for quality assurance testing. -Unlike dev, the stage environment is actually connected to a real database -(the Kuma stage environment). +Unlike dev, the stage environment is actually connected to a real database (the +Kuma stage environment). ## Dev is for experimenting -Use this environment when you can't wait for the cron schedule for stage, -or if you want to try out a specific (git) branch. +Use this environment when you can't wait for the cron schedule for stage, or if +you want to try out a specific (git) branch. -The default deployment prefix is `main` which is the first word in the domain name: -`main.content.dev.mdn.mozit.cloud`. But you can deploy to the dev environment -with a custom prefix. E.g. `web-perf-experiment123` and then the URL becomes: -`web-perf-experiment123.content.dev.mdn.mozit.cloud`. +The default deployment prefix is `main` which is the first word in the domain +name: `main.content.dev.mdn.mozit.cloud`. But you can deploy to the dev +environment with a custom prefix. E.g. `web-perf-experiment123` and then the URL +becomes: `web-perf-experiment123.content.dev.mdn.mozit.cloud`. ## With or without Kuma -The biggest difference between dev compared to prod & stage, is that the -backend API is faked in dev. This includes the ability to sign in. -Also, in prod & stage, the CDN (AWS CloudFront) is configured to fall back to -Kuma to render what can't be rendered as a static asset. +The biggest difference between dev compared to prod & stage, is that the backend +API is faked in dev. This includes the ability to sign in. Also, in prod & +stage, the CDN (AWS CloudFront) is configured to fall back to Kuma to render +what can't be rendered as a static asset. ## Tracking Whatsdeployed -These URLs give you a comparison between what's the `main` (for Yari) -and `main` (for Content) in the git repo, compared to what's made it into -each deployment environment. This helps to answer "Has my change gone live yet?" +These URLs give you a comparison between what's the `main` (for Yari) and `main` +(for Content) in the git repo, compared to what's made it into each deployment +environment. This helps to answer "Has my change gone live yet?" - [Code](https://whatsdeployed.io/s/Rzl/mdn/yari) - [Content](https://whatsdeployed.io/s/DLi/mdn/content) diff --git a/docs/envvars.md b/docs/envvars.md index e6ca959a0b1f..b5cf2c0f74bd 100644 --- a/docs/envvars.md +++ b/docs/envvars.md @@ -11,18 +11,18 @@ This document attempts to describe each environment variable. #### Default: n/a -This is a general OS, optional, environment variable and it's needed -if you want the ability to go from viewing a rendered document to -opening the source in your preferred editor. It's needed for the -"Edit this page in your editor" button to work. +This is a general OS, optional, environment variable and it's needed if you want +the ability to go from viewing a rendered document to opening the source in your +preferred editor. It's needed for the "Edit this page in your editor" button to +work. ## Builder -For the builder, a lot of environment variables can be overridden with -CLI arguments. +For the builder, a lot of environment variables can be overridden with CLI +arguments. -The general rule is that environment variables specific to the builder are -all prefixed with `CONTENT_`. E.g. `CONTENT_ROOT` +The general rule is that environment variables specific to the builder are all +prefixed with `CONTENT_`. E.g. `CONTENT_ROOT` ### `CONTENT_ROOT` @@ -36,17 +36,16 @@ Where the files are. **Example: `web/css,web/html`** -Applicable if you run batches of builds but want to limit it to only the -folders you care about. -When doing a batch build, it can be very time-consuming so just doing -one or two sub-folders will speed things up. +Applicable if you run batches of builds but want to limit it to only the folders +you care about. When doing a batch build, it can be very time-consuming so just +doing one or two sub-folders will speed things up. ### `BUILD_FILES` **Default: `[]`** -A comma or newline separated list of file paths. Can be absolute or relative -to the `CONTENT_ROOT`. +A comma or newline separated list of file paths. Can be absolute or relative to +the `CONTENT_ROOT`. ### `BUILD_OUT_ROOT` @@ -71,18 +70,17 @@ You can mix and match like this for example: macros:error, broken_links: warn, bad_bcd_queries: ignore ``` -Anything _not_ mentioned defaults to `ignore`, so the above example -is equivalent to: +Anything _not_ mentioned defaults to `ignore`, so the above example is +equivalent to: ```sh macros:error, broken_links: warn ``` -When a flaw is discovered, if the level is `error` it will, halt the build -and throw an error. It will halt on the first flaw error encountered. -If the level is `warn` it will inject the flaw message into the built -`index.json` file which you can view when rendering the document on -`http://localhost:3000/`. +When a flaw is discovered, if the level is `error` it will, halt the build and +throw an error. It will halt on the first flaw error encountered. If the level +is `warn` it will inject the flaw message into the built `index.json` file which +you can view when rendering the document on `http://localhost:3000/`. ### `BUILD_FIX_FLAWS` @@ -105,10 +103,10 @@ information about fixable flaws instead of actually fixing it on disk. **Default: `https://mdn.mozillademos.org`** -When generating live samples `