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

3 4 5 6
## Humanities

### Social contract

7
1. Use and promote welcoming behavior to respect the [Code of Conduct](https://gitlab.iscpif.fr/humanities/gargantext/blob/master/CODE_OF_CONDUCT.md)
8

9
2. We are a team as whole: here to help each others
10 11 12 13 14 15
  - knowing the unknown is a value but ignoring the unknown is a failure
    - do not ask to ask: just ask
    - there is no stupid question(s)
    - there is no unique solution(s)

3. Watch deadlines individually and collectively
16
  - at 0% of the time of the task, agree on the /estimate of time to fix the issue.
17 18 19 20
  - 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
21 22
  - 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.
23 24 25 26 27 28 29


### Facing issues

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


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

### 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:
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
* `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/

72 73

##### Git Tips
74 75
* fix the conflicts on your own branch before asking for [PR]
    * `git rebase dev` daily to make sure you do not diverge
76
* do not add temporary files in your commits
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
    * `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


### Code main guidelines

#### Code Design

Please configure your editor accordingly (ask for tips if needed or put your tips here)

##### Line length
* all line length should be < 120 chars

##### Identation
* 2 spaces or more if needed by the compiler
    * i.e. Tab character is avoided
    * avoid trailing spaces, mostly spaces at the end of lines (remove it)

* HTML nodes:

```
  div []
  [ div []
    [ a [] [...]
    , a [] [...]
    ]
  , div []
    [ ...
    , ...
    ]
  ]
```
114

115
* Record notation:
116

117 118
```
  { a: exp, b: exp }
119

120 121 122
  { a: exp
  , b: exp
  }
123

124 125 126 127 128 129
  { a :: Typ, b :: Typ }

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

131 132


133
#### Building
134

135 136 137
* to build use `./build`
* to rebuild (after a major upgrade) use `./rebuild`
* to add a new dependency: `psc-package install PACKAGE`
138

139
installation note: yarn first then psc-package are used to manage dependencies
140

141 142

#### Map of the source code
143 144 145

TODO

146
#### Components/Specs
147 148 149 150 151 152 153 154 155 156 157

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

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

158 159 160
Components modules should contain:

Assuming the component is called comp.
161

162 163 164 165 166 167 168 169 170 171 172 173 174
`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
175 176 177 178 179 180 181 182 183

```
f $ do --> f do

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

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

184
#### Using the `Show` class
185 186 187 188 189

* 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`.

190
#### When to newtype?
191 192 193 194 195 196

* 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`.


197
### Routing (backend & frontend)
198

199
#### Backend
200 201 202 203

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

204
### Thermite usage
205

206
#### Minor style rules
207 208 209 210 211 212 213 214

```
cotransform --> modifyState

void modifyState --> modifyState_

performAction should be a local function
```
215