CONTRIBUTING.md 8.01 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 6 7 8
help make it even better than it is today!

- [Contribute](#contribute)
  - [Prerequisites](#prerequisites)
  - [Get Started](#get-started)
9
  - [Standalone](#standalone)
10
  - [Test](#test)
11
  - [Scripts](#scripts)
12 13 14 15 16 17
  - [Recommended IDE Settings](#recommended-ide-settings)
  - [VS Code](#vs-code)
  - [Known Issues](#known-issues)
    - [Docker Compose](#docker-compose)
    - [Jest Watch](#jest-watch)
- [Naming Guidelines](#naming-guidelines)
18 19 20 21
  - [API-related methods](#api-related-methods)
  - [React methods](#react-methods)
  - [Redux states](#redux-states)
  - [React variables](#react-variables)
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
- [Commit Message Guidelines](#commit-message-guidelines)
  - [Revert](#revert)
  - [Type](#type)
  - [Scope](#scope)
  - [Subject](#subject)

## 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
```

The website should now be available at: http://localhost:3100.

5 sample users have been generated during setup:

- Administrator:
  - Email: `doris@sea.com`<br>
    Mot de passe: `Azerty123`
- Regional Administrator:
  - Email: `deb@sea.com`<br>
    Mot de passe: `Azerty123`
- Contributors:
  - Email: `nemo@sea.com`<br>
    Mot de passe: `Azerty123`
  - Email: `astrid@sea.com`<br>
    Mot de passe: `Azerty123`
  - Email: `marin@sea.com`<br>
    Mot de passe: `Azerty123`

67 68 69 70
### Standalone

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

71
First, change `CDTN_API_URL` value to `http://localhost:3300` in `.env` file.
72 73 74 75 76 77 78

Then run:

```sh
yarn dev:standalone
```

79 80 81 82 83 84 85 86 87
### 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`

88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
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:seed`: Seed the database via a mix of dummy and real production data.
- `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).
- `setup:full`: Setup (or refresh) a ready-to-use dev environment **with** a new seed.<br>
  _This also updates the dev/test database snapshot._
- `start`: Start a full production instance (without Docker images).
- `start:prod`: Run the production build & run script.

111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153
### Recommended IDE Settings

### VS Code

`settings.json`

```json
{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnPaste": false,
  "editor.formatOnSave": true,
  "editor.rulers": [100],
  "eslint.enable": true
}
```

`extensions.json`

```json
{
  "recommendations": [
    "alexkrechik.cucumberautocomplete",
    "dbaeumer.vscode-eslint",
    "editorconfig.editorconfig",
    "esbenp.prettier-vscode",
    "jpoissonnier.vscode-styled-components",
    "mikestead.dotenv",
    "ms-azuretools.vscode-docker",
    "ryanluker.vscode-coverage-gutters"
  ]
}
```

### 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
```
154

155
#### Jest Watch
156

157 158 159 160 161 162 163 164 165 166 167
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
```

---

## Naming Guidelines
168

169
### API-related methods
170

171
This includes React methods as well as Redux actions, action types and sagas:
172

173 174
- 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
175
  foreign entity (i.e.: `addAnswerComment()`).
176 177
- 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
178
  **remove** if it targets a foreign entity (i.e.: `removeAnswerComment()`).
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
### 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
213

214 215
- All the variables referencing a component must start with **$**
  (i.e.: `<Button ref={node => this.$button = node}>`).
216 217

---
218 219 220 221 222 223 224 225 226 227 228

## Commit Message Guidelines

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

```
<type>(<scope>): <subject>
```

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

229 230
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.
231 232 233 234 235

**Examples:**

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

238
Do not hesitate check [existing commits][link-cdtb-commits] to get a better understanding.
239 240 241

### Revert

242 243 244
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.
245 246 247 248 249 250

### Type

Must be one of the following:

- **build**: Changes that affect the build system or external dependencies.
251
- **chore**: Updates and upgrades.
252 253 254 255 256 257 258 259 260 261 262
- **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

263 264
The scope should be the name of the npm package affected (as perceived by the person reading the
changelog generated from commit messages.
265 266 267 268

The following is the list of supported scopes:

- **api**
269
- **app**
270 271 272 273 274 275 276 277 278 279 280

### 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.

---

281
[link-cdtb-commits]: https://github.com/SocialGouv/code-du-travail-backoffice/commits/master
282 283 284 285
[link-cdtn]: https://code.travail.gouv.fr
[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
[link-issue-2]: https://github.com/facebook/jest/issues/3254#issuecomment-297214395