CONTRIBUTING.md 9.97 KB
Newer Older
1 2
# Contributing

3
We would love for you to contribute to the backoffice of [Code du travail numérique][link-cdtn] and
4 5
help make it even better than it is today!

6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
- [Contributing](#contributing)
  - [Contribute](#contribute)
    - [Prerequisites](#prerequisites)
    - [Get Started](#get-started)
      - [To run on arm architecture](#to-run-on-arm-architecture)
    - [Standalone](#standalone)
    - [Test](#test)
    - [Scripts](#scripts)
    - [Recommended IDE Settings](#recommended-ide-settings)
    - [VS Code](#vs-code)
    - [Known Issues](#known-issues)
      - [Docker Compose](#docker-compose)
      - [Jest Watch](#jest-watch)
  - [Common Tasks](#common-tasks)
    - [Database backup in production](#database-backup-in-production)
    - [Database restore in production](#database-restore-in-production)
    - [Database snapshot update in development](#database-snapshot-update-in-development)
    - [Database snapshot restore in development](#database-snapshot-restore-in-development)
  - [Naming Guidelines](#naming-guidelines)
    - [API-related methods](#api-related-methods)
    - [React methods](#react-methods)
    - [Redux states](#redux-states)
    - [React variables](#react-variables)
  - [Commit Message Guidelines](#commit-message-guidelines)
    - [Revert](#revert)
    - [Type](#type)
    - [Scope](#scope)
    - [Subject](#subject)
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55

## Contribute

### Prerequisites

- Docker v19+
- Docker Compose v1.25+
- Node v12+
- Yarn v1.22+

You must be able to run `docker` and `docker-compose` [without `sudo`][link-docker-no-sudo].

### Get Started

```bash
git clone https://github.com/SocialGouv/code-du-travail-backoffice.git
cd code-du-travail-backoffice
yarn
yarn setup
yarn dev
```

56
The website should now be available at: <http://localhost:3100>.
57 58 59 60

5 sample users have been generated during setup:

- Administrator:
61
  - Email: `doris@sea.com`  
62 63
    Mot de passe: `Azerty123`
- Contributors:
64
  - Email: `nemo@sea.com`  
65 66
    Mot de passe: `Azerty123`

67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
#### To run on arm architecture

You have to change `docker-compose.yml` by replacing `postgrest` service by the following one:

```yml
postgrest:
  container_name: cdtn_backoffice_postgrest
  image: hughjfchen/hughjfchen:postgrest-aarch64-6.0.2
  restart: always
  environment:
    PGRST_DB_ANON_ROLE: ${PGRST_DB_ANON_ROLE}
    PGRST_DB_SCHEMA: ${PGRST_DB_SCHEMA}
    PGRST_DB_URI: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
    PGRST_JWT_SECRET: ${PGRST_JWT_SECRET}
  depends_on:
    - db
```

85 86 87 88
### Standalone

Standalone dev also runs [**ctdn-api**](https://github.com/SocialGouv/cdtn-api) locally:

89
First, change `CDTN_API_URL` value to `http://localhost:3300` in `.env` file.
90 91 92 93 94 95 96

Then run:

```sh
yarn dev:standalone
```

97 98 99 100 101 102 103 104 105
### Test

- All Tests: `yarn test`
- Lint Tests: `yarn test:lint`
- Type Tests: `yarn test:type`
- Unit Tests: `yarn test:unit`
- Unit Tests (watch): `yarn test:watch`
- E2E Tests: `yarn test:e2e`

106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
to update Unite Tests snapshots, you can run `yarn test:update`.

### Scripts

This repository comes with multiple useful npm scripts (run via `yarn <script>`):

- `db:backup`: Generate a database dump.
- `db:migrate` Migrate database schema.
- `db:migrate:make`: Create a new database migration file.
- `db:restore`: Restore a database dump.
- `db:snapshot:restore`: Restore the dev database dump.
- `db:snapshot:update`: Update the dev database dump file.
- `dev`: Start a full development instance (including Docker images).
- `dev:docker`: Start dev-related Docker images (with a dev config).
- `dev:packages`: Sun the packages instance in dev (watch + live-reload) mode.
- `setup`: Setup (or refresh) a ready-to-use dev environment.
- `setup:env`: Reset the dev environment variables (via the `.env` file).
- `start`: Start a full production instance (without Docker images).
- `start:prod`: Run the production build & run script.

126 127 128 129 130 131 132 133
### Recommended IDE Settings

### VS Code

`settings.json`

```json
{
134 135 136 137
  "editor.codeActionsOnSave": {
    "source.fixAll": true
  },
  "editor.defaultFormatter": "dbaeumer.vscode-eslint",
138
  "editor.formatOnSave": true,
139 140 141 142 143 144 145 146 147
  "eslint.codeActionsOnSave.mode": "all",
  "eslint.format.enable": true,
  "eslint.packageManager": "yarn",
  "[css]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
148 149 150 151 152 153 154 155 156 157 158 159 160
}
```

### Known Issues

#### Docker Compose

Under Ubuntu, if you encounter the error `double free or corruption (out)`, the [current
solution][link-issue-1] is to force-remove the related dependency:

```bash
dpkg -r --force-depends golang-docker-credential-helpers
```
161

162
#### Jest Watch
163

164 165 166 167 168 169 170 171 172 173
Under Ubuntu, if you encounter the error
`Error: ENOSPC: System limit for number of file watchers reached`, the [current
solution][link-issue-2] is to increase the number of file system watchers:

```bash
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
```

---

174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
## Common Tasks

### Database backup in production

```sh
yarn db:backup
```

will dump your Docker database generating a local `./backups/YYYY_MM_DD.sql` PosgreSQL dump file.

### Database restore in production

Supposing you have, for example, a `./backups/2021_12_10.sql` PosgreSQL dump file:

```sh
yarn db:restore 2021_12_10
```

will automatically restore this backup into your Docker database.

### Database snapshot update in development

To fasten CI and dev setup with real production PostgreSQL data, we use snapshots that are in fact
PostgreSQL dump files (taken from production backups) in which we inject a fake administrator and
contributor generated in order to use them locally (without the need to import the production
`PGRST_JWT_SECRET` environment variable which would pose a security threat).

First run a db:backup in production and download this file locally in `./backups`, then run:

```sh
yarn db:snapshot:update YYYY_MM_DD
```

This command will update `./db/snapshot.sql` with anonymzed users data and real password replaced by
fake ones. This file should be included in your git commits since this file must be shared between
developers and is also used for CI tests.

### Database snapshot restore in development

See the explanations above to understand the purpose of a database snapshot.

You shouldn't have to run this command alone since it's already run when you run a `yarn setup` but
in some case you can manually run it via:

```sh
yarn db:snapshot:restore
```

---

224
## Naming Guidelines
225

226
### API-related methods
227

228
This includes React methods as well as Redux actions, action types and sagas:
229

230 231
- All `GET` call-related methods must start with the verb **load**.
- All `POST` call-related methods must start with the verb **create**, or **add** if it targets a
232
  foreign entity (i.e.: `addAnswerComment()`).
233 234
- All `PATCH` call-related methods must start with the verb **update**.
- All `DELETE` call-related methods must start with the verb **delete** (or **\_delete**), or
235
  **remove** if it targets a foreign entity (i.e.: `removeAnswerComment()`).
236

237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269
### React methods

- All the methods returning a JSX value should start with the verb **render**.

### Redux states

A common state should look like:

```ts
interface {
  /** Single entity data (creation, edition) */
  data: Object | null;
  error: Error | null;
  /** Is it fetching data? */
  isLoading: boolean;
  /**
    Total number of entities (listing)

    @description
    This represents the number of entities available on the API and should be higher than the list
    length if there is more than one page.
  */
  length: number;
  /** Multiple entities data (listing) */
  list: Object[];
  /** Current page index (listing) */
  pagesIndex: number;
  /** Total number of pages (listing) */
  pagesLength: number;
}
```

### React variables
270

271 272
- All the variables referencing a component must start with **$** (i.e.:
  `<Button ref={node => this.$button = node}>`).
273 274

---
275 276 277 278 279

## Commit Message Guidelines

Each commit message consists of a **type**, a **scope** and a **subject**:

280
```text
281 282 283 284 285
<type>(<scope>): <subject>
```

The **type** is mandatory and the **scope** of the header is optional.

286 287
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
to read on GitHub as well as in various git tools.
288 289 290 291 292

**Examples:**

- `docs(changelog): update changelog to 1.12.5`
- `fix(release): need to depend on latest rxjs and zone.js`
293
- `ci(codecov): configure dependabot`
294

295
Do not hesitate check [existing commits][link-cdtb-commits] to get a better understanding.
296 297 298

### Revert

299 300 301
If the commit reverts a previous commit, it should begin with `revert:`, followed by the header of
the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the
SHA of the commit being reverted.
302 303 304 305 306 307

### Type

Must be one of the following:

- **build**: Changes that affect the build system or external dependencies.
308
- **chore**: Updates and upgrades.
309 310 311 312 313 314 315 316 317 318 319
- **ci**: Changes to our CI configuration files and scripts.
- **docs**: Documentation only changes.
- **feat**: A new feature.
- **fix**: A bug fix.
- **perf**: A code change that improves performance.
- **refactor**: A code change that neither fixes a bug nor adds a feature.
- **style**: Changes that do not affect the meaning of the code.
- **test**: Adding missing tests or correcting existing tests.

### Scope

320 321
The scope should be the name of the npm package affected (as perceived by the person reading the
changelog generated from commit messages.
322 323 324 325

The following is the list of supported scopes:

- **api**
326
- **app**
327 328 329 330 331 332 333 334 335 336 337

### Subject

The subject contains a succinct description of the change:

- Use the imperative, present tense: "change" not "changed" nor "changes".
- Don't capitalize the first letter.
- No dot (.) at the end.

---

338
[link-cdtb-commits]: https://github.com/SocialGouv/code-du-travail-backoffice/commits/master
339
[link-cdtn]: https://code.travail.gouv.fr
340 341 342 343
[link-docker-no-sudo]:
  https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user
[link-issue-1]:
  https://github.com/docker/docker-credential-helpers/issues/103#issuecomment-421822269
344
[link-issue-2]: https://github.com/facebook/jest/issues/3254#issuecomment-297214395