CONTRIBUTING.md 4.22 KB
Newer Older
1 2 3 4 5 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 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 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
# Contributing

## Launching the app

First install the dependencies

```bash
yarn
```

Then copy the example env file

```bash
cp .env.example .env
```

(Optionnal) Install the React Developper Tools in your chrome browser. Then, find the extension install path and add it to the .env file. More info [here](https://electronjs.org/docs/tutorial/devtools-extension). You must provide the absolute path.


You should use autoreloading when developping, using

```bash
yarn dev
```

and in another terminal, to launch the electron app:

```bash
yarn dev-app
```

and then, reload your electron app with the refresh command (`CMD + R` on OS X)

You can make the app automatically load a specific folder by doing:

```bash
yarn dev --autoload /absolute/or/relative/path/to/folder
```


## Writing code

- Use JSDoc comments to document new functions.
- Try to keep you methods simple using meaningful function names and variable names. 

## Comitting

For our commits message, we are following [conventional commits](https://www.conventionalcommits.org).

## Tests

### Unit tests

You can run unit tests by running

```bash
yarn test
```

### e2e tests

You can run end-to-end tests by running

```bash
yarn e2e
```

E2E tests may fail after you installed new dependencies. You can fix it by doing

```bash
yarn install --force
```

## Resource consuming tasks

When doing heavy resource consuming tasks, we use NodeJS `childProcess.fork` method to keep the UI reactive. To do so,
we use [webpack-fork-loader](https://www.npmjs.com/package/webpack-fork-loader), which will wrap every `*.fork.js` or
`*.fork.ts` file into a ChildProcess constructor that will build a nodeJS ChildProcess element.

We added some utility classes to adapt the ChildProcess API to the formerly used WebWorkers API which can be found in
the `src/util/async-worker-util.ts` file.

A basic new ChildProcess would look like :

```typescript
// child-process.controller.ts
import MyChildProcess from "./child-process.fork.ts";
88 89 90
import { createAsyncWorkerForChildProcessControllerFactory } from "util/async-worker/child-process";
import { MessageTypes } from "util/batch-process/batch-process-util-types";
import { cancelableBackgroundWorkerProcess$ } from "util/batch-process/batch-process-util";
91 92

export const runMyChildProcess = () => {
93 94
    // We build a factory that return the AsyncWorker object. The parameter is the child process file name
    const asyncProcessFactory = createAsyncWorkerForChildProcessControllerFactory("my-child-process.fork");
95

96 97 98
    const result$ = cancelableBackgroundWorkerProcess$({ data }, asyncProcessFactory);
    
    // use the result observable
99 100
}
```
101

102
```typescript
103
// my-child-process.fork.ts
104
import { MessageTypes } from "../util/batch-process/batch-process-util-types";
105 106
import { createAsyncWorkerForChildProcess } from "util/async-worker/child-process";
import { setupChildWorkerListeners } from "util/async-worker/async-worker-util";
107 108 109

const asyncWorker = createAsyncWorkerForChildProcess();

110 111 112 113
setupChildWorkerListeners(asyncWorker, {
    onInitialize: () => console.log("handleInitializeMessage"),
    onData: () => console.log("handleDataMessage"),
})
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
```

## Translations

Translations are managed using i18n json files in `src/translations/`. To make it easier for translators to work, we
created a script that allows to generate csv containing the english text (which is our reference) and another
language translation. This will simplify identifying the missing translations. To do that, simply run :

```bash
yarn generate-translation-csv
```

You will then find your translations csv in the `./translations` folder.

Once your translator filled the CSV, you can import it back. Assuming that the first column of the csv is the path,
the second your reference language and the following columns the translated languages, you can do, for a file that
contains french translation in the third column and german translation in the fourth:

```bash
yarn import-translation-csv ./translations/fr-de.csv fr de
```

## Pull requests

If you want to contribute, you must respect our linter specs. You can run `yarn lint` for compliance test.

You are welcome to open pull requests to add features to the project.

We are trying to improve our test coverage, so you are welcome to test the services you are adding.