Skip to content

Commit a3e95d1

Browse files
Ve33yovflowd
Ve33y
and
ovflowd
authored
Docs: updates to contributing, collaborator, translation (#5420)
Co-authored-by: Claudio Wunder <[email protected]>
1 parent 2d8d205 commit a3e95d1

File tree

3 files changed

+131
-118
lines changed

3 files changed

+131
-118
lines changed

‎COLLABORATOR_GUIDE.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@
77
- [Adding new pages](#adding-new-pages)
88
- [Create the page content](#create-the-page-content)
99
- [Translating pages](#translating-pages)
10+
- [Creating Components](#creating-components)
11+
- [Best practices when creating a Component](#best-practices-when-creating-a-component)
12+
- [How a new Component should look like when freshly created](#how-a-new-component-should-look-like-when-freshly-created)
13+
- [Best practices for Component development in general](#best-practices-for-component-development-in-general)
14+
- [Unit Tests and Storybooks](#unit-tests-and-storybooks)
15+
- [General Guidelines for Unit Tests](#general-guidelines-for-unit-tests)
16+
- [General Guidelines for Storybooks](#general-guidelines-for-storybooks)
1017

1118
This document contains information for Collaborators of the Node.js
1219
website project regarding maintaining the code, documentation and issues.
@@ -111,3 +118,121 @@ layout: contribute.hbs
111118
### Translating pages
112119

113120
See [TRANSLATION.md](./TRANSLATION.md) for the website translation policy.
121+
122+
## Creating Components
123+
124+
The Node.js Website uses **React.js** as a Frontend Library for the development of the Website. React allows us to create user interfaces with a modern take on Web Development.
125+
126+
If you're unfamiliar with React or Web Development in general, we encourage a read before taking on complex issues and tasks as this repository is **not for educational purposes** and we expect you to have a basic understanding of the technologies used.
127+
128+
We also recommend getting familiar with technologies such as [Next.js][], [MDX][], [SCSS][] and "concepts" such as "CSS Modules" and "CSS-in-JS".
129+
130+
### Best practices when creating a Component
131+
132+
- All React Components should be placed within the `components` folder.
133+
- Each Component should be placed whenever possible within a sub-folder, which we call the "Domain" of the Component
134+
- The domain is the representation of where these Components belong to or where will be used.
135+
- For example, Components used within Article Pages or that are part of the structure of an Article or the Article Layouts, should be placed within `components/Article`
136+
- Each component should have its own folder with the name of the Component
137+
- The structure of each component folder follows the following template:
138+
```text
139+
- ComponentName
140+
- index.tsx // the component itself
141+
- index.module.scss // all styles of the component are placed there
142+
- index.stories.tsx // component Storybook stories
143+
- __tests__ // component tests (such as unit tests, etc)
144+
- index.test.tsx
145+
```
146+
- React Hooks belonging to a single Component should be placed within the Component's folder
147+
- If the Hook as a wider usability or can be used by other Components, then it should be placed at the root `hooks` folder.
148+
- If the Component has "sub-components" they should follow the same philosophy as the Component itself.
149+
- For example, if the Component `ComponentName` has a sub-component called `SubComponentName`, then it should be placed within `ComponentName/SubComponentName`
150+
151+
#### How a new Component should look like when freshly created
152+
153+
```tsx
154+
import styles from './index.module.scss';
155+
import type { FC } from 'react';
156+
157+
type MyComponentProps = {}; // The types of the Props of your Component
158+
159+
const MyComponent: FC<MyComponentProps> = ({ prop1, prop2... }) => (
160+
// Actual code of my Component
161+
);
162+
163+
export default MyComponent;
164+
```
165+
166+
### Best practices for Component development in general
167+
168+
- Only spread props `{ ... }` on the definition of the Component (Avoid having a variable named `props`)
169+
- Avoid importing `React`, only import the modules from React that you need
170+
- When importing types use `import type { NameOfImport } from 'module'`
171+
- When defining a Component use the `FC` type from React to define the type of the Component
172+
- When using `children` as a prop, use the `FC<PropsWithChildren<MyComponentProps>>` type instead
173+
- Alterenatively you can define your type as `type MyComponentProps = PropsWithChildren<{ my other props}>`
174+
- Each Props type should be prefixed by the name of the Component
175+
- Components should always be the `default` export of a React Component file
176+
- Avoid using DOM/Web APIs/`document`/`window` API access within a React Component. Use utilities or Hooks when you need a Reactive state
177+
- Avoid making your Component too big. Deconstruct it into smaller Components/Hooks whenever possible
178+
179+
## Unit Tests and Storybooks
180+
181+
Each new feature or bug fix should be accompanied by a unit test (when deemed valuable). We use [Jest][] as our test runner and [React Testing Library][] for our React unit tests.
182+
183+
We also use [Storybook][] to document our components. Each component should have a storybook story that documents the component's usage. Snapshot testing of our components is directly done by taking snapshot of all Storybook stories, using [Storybook Test Runner][] and [Playwright][].
184+
185+
### General Guidelines for Unit Tests
186+
187+
Unit Tests are fundamental to ensure that code changes do not disrupt the functionalities of the Node.js Website:
188+
189+
- We recommend that unit tests are added for content covering `util`, `scripts`, `hooks` and `components` whenever possible.
190+
- Unit Tests should cover that the functionality of a given change is working as expected.
191+
- When creating unit tests for React components, we recommend that the tests cover all the possible states of the component.
192+
- We also recommend mocking external dependencies, if unsure about how to mock a certain dependency, raise the question on your Pull Request.
193+
- We recommend using [Jest's Mock Functions](https://jestjs.io/docs/en/mock-functions) for mocking dependencies.
194+
- We recommend using [Jest's Mock Modules](https://jestjs.io/docs/en/manual-mocks) for mocking dependencies that are not available on the Node.js runtime.
195+
- Common Providers and Contexts from the lifecycle of our App, such as [`react-intl`][] should not be mocked but given an empty or fake context whenever possible.
196+
- We recommend reading previous unit tests from the codebase for inspiration and code guidelines.
197+
198+
### General Guidelines for Storybooks
199+
200+
Storybooks are an essential part of our development process. They help us to document our components and to ensure that the components are working as expected.
201+
202+
They also allow Developers to preview Components and be able to test them manually/individually to the smallest unit of the Application. (The individual Component itself).
203+
204+
**Storybooks should be fully typed and follow the following template:**
205+
206+
```tsx
207+
import type { Meta as MetaObj, StoryObj } from '@storybook/react';
208+
import NameOfComponent from './index';
209+
210+
type Story = StoryObj<typeof NameOfComponent>;
211+
type Meta = MetaObj<typeof NameOfComponent>;
212+
213+
// If the component has any props that are interactable, they should be passed here
214+
// We recommend reading Storybook docs for args: https://storybook.js.org/docs/react/writing-stories/args
215+
export const Default: Story = {};
216+
217+
// If the Component has more than one State/Layout/Variant, there should be one Story for each variant
218+
export const AnotherStory: Story = {
219+
args: {},
220+
};
221+
222+
export default { component: NameOfComponent } as Meta;
223+
```
224+
225+
- Stories should have `args` whenever possible, we want to be able to test the different aspects of a Component
226+
- Please follow the template above to keep the Storybooks as consistent as possible
227+
- We recommend reading previous Storybooks from the codebase for inspiration and code guidelines.
228+
- If you need to decorate/wrap your Component/Story with a Container/Provider, please use [Storybook Decorators](https://storybook.js.org/docs/react/writing-stories/decorators)
229+
230+
[Jest]: https://jestjs.io/
231+
[React Testing Library]: https://testing-library.com/docs/react-testing-library/intro/
232+
[Storybook]: https://storybook.js.org/
233+
[Storybook Test Runner]: https://storybook.js.org/addons/@storybook/test-runner#dom-snapshot-recipe
234+
[Playwright]: https://playwright.dev/
235+
[`react-intl`]: https://formatjs.io/docs/react-intl/
236+
[Next.js]: https://nextjs.org/
237+
[MDX]: https://mdxjs.com/
238+
[SCSS]: https://sass-lang.com/

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,8 @@ Thank you for your interest in contributing to the Node.js Website. Before you p
55
- [Code of Conduct](https://github.com/nodejs/node/blob/HEAD/CODE_OF_CONDUCT.md)
66
- [Getting started](#getting-started)
77
- [Vocabulary](#vocabulary)
8-
- [Creating Components](#creating-components)
8+
- [Standards for making code changes](#standards-for-making-code-changes)
99
- [Commit message guidelines](#commit-guidelines)
10-
- [Unit Tests and Storybooks](#unit-tests-and-storybooks)
1110
- [Pull Request Policy](#pull-request-policy)
1211
- [Before merging](#before-merging)
1312
- [When merging](#when-merging)
@@ -116,62 +115,9 @@ We also offer other commands that offer you assistance during your local develop
116115
or contributes in some other way.
117116
- A **Collaborator** is a contributor with write access to the repository. See [here](#becoming-a-collaborator) on how to become a collaborator.
118117

119-
## Creating Components
118+
## Standards for making code changes
120119

121-
The Node.js Website uses **React.js** as a Frontend Library for the development of the Website. React allows us to create user interfaces with a modern take on Web Development.
122-
123-
If you're unfamiliar with React or Web Development in general, we encourage a read before taking on complex issues and tasks as this repository is **not for educational purposes** and we expect you to have a basic understanding of the technologies used.
124-
125-
We also recommend getting familiar with technologies such as [Next.js][], [MDX][], [SCSS][] and "concepts" such as "CSS Modules" and "CSS-in-JS".
126-
127-
### Best Practices when creating a Component
128-
129-
- All React Components should be placed within the `components` folder.
130-
- Each Component should be placed whenever possible within a sub-folder, which we call the "Domain" of the Component
131-
- The domain is the representation of where these Components belong to or where will be used.
132-
- For example, Components used within Article Pages or that are part of the structure of an Article or the Article Layouts, should be placed within `components/Article`
133-
- Each component should have its own folder with the name of the Component
134-
- The structure of each component folder follows the following template:
135-
```text
136-
- ComponentName
137-
- index.tsx // the component itself
138-
- index.module.scss // all styles of the component are placed there
139-
- index.stories.tsx // component Storybook stories
140-
- __tests__ // component tests (such as unit tests, etc)
141-
- index.test.tsx
142-
```
143-
- React Hooks belonging to a single Component should be placed within the Component's folder
144-
- If the Hook as a wider usability or can be used by other Components, then it should be placed at the root `hooks` folder.
145-
- If the Component has "sub-components" they should follow the same philosophy as the Component itself.
146-
- For example, if the Component `ComponentName` has a sub-component called `SubComponentName`, then it should be placed within `ComponentName/SubComponentName`
147-
148-
#### How a new Component should look like when freshly created
149-
150-
```tsx
151-
import styles from './index.module.scss';
152-
import type { FC } from 'react';
153-
154-
type MyComponentProps = {}; // The types of the Props of your Component
155-
156-
const MyComponent: FC<MyComponentProps> = ({ prop1, prop2... }) => (
157-
// Actual code of my Component
158-
);
159-
160-
export default MyComponent;
161-
```
162-
163-
### Best practices for Component development in general
164-
165-
- Only spread props `{ ... }` on the definition of the Component (Avoid having a variable named `props`)
166-
- Avoid importing `React`, only import the modules from React that you need
167-
- When importing types use `import type { NameOfImport } from 'module'`
168-
- When defining a Component use the `FC` type from React to define the type of the Component
169-
- When using `children` as a prop, use the `FC<PropsWithChildren<MyComponentProps>>` type instead
170-
- Alterenatively you can define your type as `type MyComponentProps = PropsWithChildren<{ my other props}>`
171-
- Each Props type should be prefixed by the name of the Component
172-
- Components should always be the `default` export of a React Component file
173-
- Avoid using DOM/Web APIs/`document`/`window` API access within a React Component. Use utilities or Hooks when you need a Reactive state
174-
- Avoid making your Component too big. Deconstruct it into smaller Components/Hooks whenever possible
120+
Refer to the [Collaborator Guide](COLLABORATOR_GUIDE.md#code-editing) for guidelines on code writing and editing.
175121

176122
## Commit Guidelines
177123

@@ -186,57 +132,6 @@ Commits should be signed. You can read more about [Commit Signing][] here.
186132
- Commit messages **must** start with a capital letter
187133
- Commit messages **must not** end with a period `.`
188134

189-
## Unit Tests and Storybooks
190-
191-
Each new feature or bug fix should be accompanied by a unit test (when deemed valuable). We use [Jest][] as our test runner and [React Testing Library][] for our React unit tests.
192-
193-
We also use [Storybook][] to document our components. Each component should have a storybook story that documents the component's usage. Snapshot testing of our components is directly done by taking snapshot of all Storybook stories, using [Storybook Test Runner][] and [Playwright][].
194-
195-
### General Guidelines for Unit Tests
196-
197-
Unit Tests are fundamental to ensure that code changes do not disrupt the functionalities of the Node.js Website:
198-
199-
- We recommend that unit tests are added for content covering `util`, `scripts`, `hooks` and `components` whenever possible.
200-
- Unit Tests should cover that the functionality of a given change is working as expected.
201-
- When creating unit tests for React components, we recommend that the tests cover all the possible states of the component.
202-
- We also recommend mocking external dependencies, if unsure about how to mock a certain dependency, raise the question on your Pull Request.
203-
- We recommend using [Jest's Mock Functions](https://jestjs.io/docs/en/mock-functions) for mocking dependencies.
204-
- We recommend using [Jest's Mock Modules](https://jestjs.io/docs/en/manual-mocks) for mocking dependencies that are not available on the Node.js runtime.
205-
- Common Providers and Contexts from the lifecycle of our App, such as [`react-intl`][] should not be mocked but given an empty or fake context whenever possible.
206-
- We recommend reading previous unit tests from the codebase for inspiration and code guidelines.
207-
208-
### General Guidelines for Storybooks
209-
210-
Storybooks are an essential part of our development process. They help us to document our components and to ensure that the components are working as expected.
211-
212-
They also allow Developers to preview Components and be able to test them manually/individually to the smallest unit of the Application. (The individual Component itself).
213-
214-
**Storybooks should be fully typed and follow the following template:**
215-
216-
```tsx
217-
import type { Meta as MetaObj, StoryObj } from '@storybook/react';
218-
import NameOfComponent from './index';
219-
220-
type Story = StoryObj<typeof NameOfComponent>;
221-
type Meta = MetaObj<typeof NameOfComponent>;
222-
223-
// If the component has any props that are interactable, they should be passed here
224-
// We recommend reading Storybook docs for args: https://storybook.js.org/docs/react/writing-stories/args
225-
export const Default: Story = {};
226-
227-
// If the Component has more than one State/Layout/Variant, there should be one Story for each variant
228-
export const AnotherStory: Story = {
229-
args: {},
230-
};
231-
232-
export default { component: NameOfComponent } as Meta;
233-
```
234-
235-
- Stories should have `args` whenever possible, we want to be able to test the different aspects of a Component
236-
- Please follow the template above to keep the Storybooks as consistent as possible
237-
- We recommend reading previous Storybooks from the codebase for inspiration and code guidelines.
238-
- If you need to decorate/wrap your Component/Story with a Container/Provider, please use [Storybook Decorators](https://storybook.js.org/docs/react/writing-stories/decorators)
239-
240135
## Pull Request Policy
241136

242137
### Before merging
@@ -301,13 +196,4 @@ If something is missing here, or you feel something is not well described, feel
301196

302197
[`squash`]: https://help.github.com/en/articles/about-pull-request-merges#squash-and-merge-your-pull-request-commits
303198
[Conventional Commits]: https://www.conventionalcommits.org/
304-
[Commit Signing]: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits
305-
[Jest]: https://jestjs.io/
306-
[React Testing Library]: https://testing-library.com/docs/react-testing-library/intro/
307-
[Storybook]: https://storybook.js.org/
308-
[Storybook Test Runner]: https://storybook.js.org/addons/@storybook/test-runner#dom-snapshot-recipe
309-
[Playwright]: https://playwright.dev/
310-
[`react-intl`]: https://formatjs.io/docs/react-intl/
311-
[Next.js]: https://nextjs.org/
312-
[MDX]: https://mdxjs.com/
313-
[SCSS]: https://sass-lang.com/
199+
[Commit Signing]: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits

‎TRANSLATION.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@ Fill the language object with the following fields:
4040
| `hrefLang` | The language code in [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format | `fr` |
4141
| `enabled` | If the language is enabled or not | `true` |
4242

43+
Please also add the new locale file to the locales folder `/i18n/locales` and import it in the `/i18n/locales/index.mjs` file.
44+
4345
## Adding new Translation Keys
4446

4547
If you're making a new Component and adding Translation Keys for your Component, they should follow these guidelines:

0 commit comments

Comments
 (0)