# Guidelines to Contribute to the project ## Humanities ### Social contract 1. Be nice, welcome and treat others with respect: [Code of Conduct](https://gitlab.iscpif.fr/humanities/gargantext/blob/master/CODE_OF_CONDUCT.md) 2. We are a team as whole: here to help each other - knowing the unknown is a value but ignoring the unknown is a failure - do not ask to ask: just ask - there are no stupid questions 3. Watch deadlines individually and collectively - at 0% of the time of the task, agree on the /estimate of time to fix the issue. - 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 - 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. ### Facing issues If you get stuck on a bug: * Set a timer for 1h * Make it reproducible * Commit a version with the issue even if the code is work-in-progress [WIP] and if help is needed [HELP]. * Try to identify the root cause of the issue: * Using the browser inspector * Identify the code path * If it takes too long fill an issue and mark it as blocking. Mention it on IRC and go to another task. ### Coordination tools ### 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: * `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/ ##### Git Tips * fix the conflicts on your own branch before asking for [PR] * `git rebase dev` daily to make sure you do not diverge * do not add temporary files in your commits * `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 Please configure your editor accordingly (ask for tips if needed or put your tips here) ### Code guidelines #### Basics 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 * HTML nodes: ``` div {...} [ div {...} [ a {} [...], a {...} [...] ] , div {...} , div { ... , ... } [ ... , ... ] ] ``` * Record notation: ``` { a: exp, b: exp } { a: exp , b: exp } { a :: Typ, b :: Typ } { a :: Typ , b :: Typ } ``` #### Building * to build use `./build` * to rebuild (after a major upgrade) use `./rebuild` * to add a new dependency: `psc-package install PACKAGE` installation note: yarn first then psc-package are used to manage dependencies #### Map of the source code TODO #### Components/Specs * Small: one file in `Gargantext/Components/X.purs` * Medium/Big: ``` Gargantext/Components/ X.purs X/Types.purs X/Specs.purs (only if big) ``` Components modules should contain: Assuming the component is called comp. `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 ``` f $ do --> f do f (do ...) --> f do if (expr == true) --> if expr ``` #### Using the `Show` class * 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`. #### When to newtype? * 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`. ### Routing (backend & frontend) #### Backend Use `toUrl` Use `Config.REST` (`get`, `put`...) ### Thermite usage #### Minor style rules ``` cotransform --> modifyState void modifyState --> modifyState_ performAction should be a local function ```