CONTRIBUTING.md 5.39 KB
Newer Older
1
# Guidelines to Contribute to the project
2

3 4 5 6
## Humanities

### Social contract

James Laver's avatar
James Laver committed
7
1. Be nice, welcome and treat others with respect: [Code of Conduct](https://gitlab.iscpif.fr/humanities/gargantext/blob/master/CODE_OF_CONDUCT.md)
8

James Laver's avatar
James Laver committed
9
2. We are a team as whole: here to help each other
10 11
  - knowing the unknown is a value but ignoring the unknown is a failure
    - do not ask to ask: just ask
James Laver's avatar
James Laver committed
12
    - there are no stupid questions
13 14

3. Watch deadlines individually and collectively
15
  - at 0% of the time of the task, agree on the /estimate of time to fix the issue.
16 17 18 19
  - at 50% of the estimated time of the task, push your last commit with ID of the issue.
    - if the commit has [WIP] label: everything is fine as expected
    - if the commit has [HELP] label: it warns members of the project some
    - if the commit is not pushed, it warns the project manager something is going wrong
20 21
  - at 100% of the time of the task, push your commit with ID of the issue with the label [PR] for Pull Request and fill /spent time as comment on the issue
    - if the commit is not pushed, it warns all the team something is going wrong.
22 23 24 25 26 27 28


### Facing issues

If you get stuck on a bug:
* Set a timer for 1h
* Make it reproducible
29
  * Commit a version with the issue even if the code is work-in-progress [WIP] and if help is needed [HELP].
30 31 32
* Try to identify the root cause of the issue:
  * Using the browser inspector
  * Identify the code path
33
* If it takes too long fill an issue and mark it as blocking. Mention it on IRC and go to another task.
34 35


36
### Coordination tools
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51

### IRC Interactions
- OFTC #gargantext
- contribute to the 2 weekly meetings
- your nickname is personal and is used by the same person always

### Code coordination

Git is the main Concurrent Version system used by the project.
[gitlab](https://gitlab.iscpif.fr) is used as development platform
(others platforms are used for communication purpose mainly).

#### Git branches

Main branches are:
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
* `master`  : stable and prod version used by end users
* `testing` : candidate version for stable, tested by end users
* `dev`     : unstable version for developers only

#### Adding a new feature / fixing an issue

1. You should have an open issue in gitlab with number ~#XXX~.
2. ~git checkout -b issue-XXX-issue-short-description~
3. work... ~git commit~ many times
4. Optionally you can clean up your git log history with ~git rebase -i master~
5. Test locally ~./build.sh (TODO && ./build/run-tests.sh)
6. ~git push -u~ will push and create the branch on gitlab
7. Open a PR. In the PR reference the issue by writing (~Close #XXX~ or
   ~Connects to #XXX~).
8. Make changes according to PR feedbacks
9. Either use the =Squash & Merge button= in github or manually rebase. Please
   take the time to write a good commit message. For example be inspired by
   https://chris.beams.io/posts/git-commit/

71 72

##### Git Tips
73 74
* fix the conflicts on your own branch before asking for [PR]
    * `git rebase dev` daily to make sure you do not diverge
75
* do not add temporary files in your commits
76 77 78 79 80 81 82 83
    * `git add -p` to review what you are about to commit
* Settings to avoid trailing whitespaces and tab characters:
  `git config --global core.whitespace blank-at-eof,blank-at-eol,tab-in-indent`
  `git config --global apply.whitespace fix`


## Technicals

James Laver's avatar
James Laver committed
84
Please configure your editor accordingly (ask for tips if needed or put your tips here)
85

James Laver's avatar
James Laver committed
86
### Code guidelines
87

James Laver's avatar
James Laver committed
88
#### Basics
89

James Laver's avatar
James Laver committed
90 91 92 93 94 95 96 97 98 99 100 101 102
Line length:

* Good lines of code are no more than 80 characters long.
* Acceptable lines of code are no more than 100
* Bad lines of code are no more than 120.

Whitespace:

* 2 spaces per indentation stop, or more if needed by the compiler
* Do not use tab characters.
* Remove trailing whitespace from lines. Includes blank lines.

#### Layout
103 104 105 106 107 108



* HTML nodes:

```
James Laver's avatar
James Laver committed
109 110 111 112 113 114 115
  div {...}
  [ div {...} [ a {} [...], a {...} [...] ]
  , div {...}
  , div
    { ...
    , ...
    }
116 117 118 119 120
    [ ...
    , ...
    ]
  ]
```
121

122
* Record notation:
123

124 125
```
  { a: exp, b: exp }
126

127 128 129
  { a: exp
  , b: exp
  }
130

131 132 133 134 135 136
  { a :: Typ, b :: Typ }

  { a :: Typ
  , b :: Typ
  }
```
137

138 139


140
#### Building
141

142 143 144
* to build use `./build`
* to rebuild (after a major upgrade) use `./rebuild`
* to add a new dependency: `psc-package install PACKAGE`
145

146
installation note: yarn first then psc-package are used to manage dependencies
147

148 149

#### Map of the source code
150 151 152

TODO

153
#### Components/Specs
154 155 156 157 158 159 160 161 162 163 164

* Small: one file in `Gargantext/Components/X.purs`
* Medium/Big:

```
  Gargantext/Components/
    X.purs
    X/Types.purs
    X/Specs.purs (only if big)
```

165 166 167
Components modules should contain:

Assuming the component is called comp.
168

169 170 171 172 173 174 175 176 177 178 179 180 181
`type Props` unless it is `{}`
`type State` unless it is `{}`
`type Action` unless it is `Void`

```
compSpec :: Spec ...
compClass :: ReactClass ...
compElt :: Props -> ReactElement
```

### Purescript specific

#### Minor style rules
182 183 184 185 186 187 188 189 190

```
f $ do --> f do

f (do ...) --> f do

if (expr == true) --> if expr
```

191
#### Using the `Show` class
192 193 194 195 196

* Always use generic deriving.
* If we want a different output than the generic one it
  means that we should use a different class than `Show`.

197
#### When to newtype?
198 199 200 201 202 203

* When we need type class instances.
* When the type is generic (`Int`, `String`).
* In particular a `newtype` is not needed for records such as `State`.


204
### Routing (backend & frontend)
205

206
#### Backend
207 208 209 210

Use `toUrl`
Use `Config.REST` (`get`, `put`...)

211
### Thermite usage
212

213
#### Minor style rules
214 215 216 217 218 219 220 221

```
cotransform --> modifyState

void modifyState --> modifyState_

performAction should be a local function
```
222