Skip to content

Commit

Permalink
chore(prettier): update existing markdown files to reflect new rules
Browse files Browse the repository at this point in the history
  • Loading branch information
@LeoMcA
LeoMcA committed Apr 21, 2022
1 parent d9e646d commit b37308d
Show file tree
Hide file tree
Showing 30 changed files with 740 additions and 658 deletions.
9 changes: 6 additions & 3 deletions CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
@@ -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.
172 changes: 89 additions & 83 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -19,21 +19,23 @@ Before you can start working with Yari, you need to:
So for now let's make an exception. -->
<!-- markdownlint-disable list-marker-space -->

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):

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.

<!-- markdownlint-enable list-marker-space -->

Expand Down Expand Up @@ -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
Expand All @@ -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 <http://localhost:3000>) and the `server` (on <http://localhost:5042>).
The `yarn start` command encapsulates the front-end dev server (on
<http://localhost:3000>) and the `server` (on <http://localhost:5042>).

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
<http://localhost:3000> and click the "Open in your editor" button.

### How the server works
Expand All @@ -147,39 +154,37 @@ 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

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)
Expand Down Expand Up @@ -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 <http://localhost:3000>. 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 <http://localhost:3000>. 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

Expand All @@ -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`

Expand All @@ -271,16 +277,16 @@ 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
yarn install

### `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
13 changes: 9 additions & 4 deletions client/src/banners/README.md
View file
Original file line number Diff line number Diff line change
@@ -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";
Expand All @@ -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:

Expand All @@ -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({
Expand Down
Loading

0 comments on commit b37308d

Please sign in to comment.