courses/30.about/10.contributing/page.en.md

title	slug
Contributing	contributing

Philosophy

Each course is subject to the license its original authors chose. Translations should probably follow the same license as the original works.

! @cmeny Drop a line here about the structure with 4 levels.

How it works

• 📖 Flat files
  • enhanced markdown for content
  • YAML frontmatter for metadata
• 🦊 Continuous integration using GitLab (Ruby)
  • edit courses from your browser, using GitLab's WebIDE
• 🌎 Decentralized versioning using Git
  • asynchronous and offline collaboration
  • scales to thousands of contributors
• 🚀 HTML generation using Grav (PHP)
  • basically the new WordPress, but much better
  • vibrant and growing community in 2019

Data Flow

Here's a breakdown of three different ways of contributing to the courses.

graph RL

User(Teacher)
Website[M3P2 Website]
Local[Local Website]
Git[Git]
GitLab[GitLab]

User --> |contributes via| Git
User --> |contributes via| GitLab
User --> |contributes via| Local

Local --> |triggers| Git
Git --> |triggers| GitLab
GitLab --> |updates| Website

🐠

Via GitLab

You only need a modern browser to use the WebIDE.

!!! GitLab's preview may differ slightly from the end result.

Via Git

Setting up a Git client can be intimidating, but it allows offline edition of the courses. You can use your favorite text editor.

Here are some Git GUI clients, if the CLI feels too hard.

Note that during the alpha we're using port 10022 for ssh.

Via Local Website

This third level of edition is for experts who can run the website locally to instantly preview their changes, and use the powerful Grav's admin tools for page edition.

Enhanced Markdown

The point of Markdown (compared to raw HTML) is the readability of the source.

Markdown Cheatsheet

# Header like h1
## Header like h2
…
###### Header like h6

_italic_
__underlined__
*bold*
**strong**
~~strike-through~~

`inline->code()`

```python
import antigravity
antigravity.apply()
```


Go [there](https://…)
[Current chapter](.)
[Parent chapter](..)
[Sibling chapter](../another-chapter)
[Child chapter](chapter)
[Anchor in the page](#slug-of-header)

![Description of the image](local-image.png)

! blue notice
!! green notice
!!! orange notice
!!!! red notice
!!!!
!!!! another line on the red notice

More at Gitlab's Markdown documentation.

Emoticons ✨

Just type or paste the unicode character, modern browsers will do the rest.

Here's a handy list: https://unicode.org/emoji/charts/full-emoji-list.html

LateX

You can use LateX in the courses.

For example, the following

$E = m \cdot c^2$

yields $E = m \cdot c^2$

!!!! Make sure to add trailing spaces to expressions like \cdot, !!!! or you'll end up with broken formulas.

Multiline

The preferred way is to use a math code block, like so:

```math
\overrightarrow{F}_{L} = q \cdot (
    \overrightarrow{E}
    +
    \overrightarrow{v}
    \wedge
    \overrightarrow{B}
)
```

The math code block also works in GitLab's preview.

You can also use the $$ syntax, but GitLab won't understand it.

!! Generous spacing greatly improves the readability of the source.

Flowcharts

Any resemblance to real persons, living or dead, is purely coincidental.

graph TB
  subgraph M3P2
    Draft[Draft]
    File[File]
    Website[Website]
    Pipeline[Pipeline]
  end

  Sponsor((Sponsor))
  Teacher((Teacher))
  Student((Student))
  Engineer((Engineer))

  Student --> |studies| Website
  Student --> |loves| Sponsor
  Student --> |respects| Teacher
  Student --> |complements| Draft
  Teacher -.- Engineer
  Sponsor --> |feeds| Teacher
  Sponsor --> |feeds| Engineer
  Teacher --> |reviews| Draft
  File --> |triggers| Pipeline
  Draft -.- File
  Pipeline --> |updates| Website
  Teacher --> |authors| File
  Engineer --> |specifies| File
  Engineer --> |maintains| Pipeline
  Engineer --> |hosts| Website

```mermaid
graph TB
  subgraph M3P2
    Draft[Draft]
    File[File]
    Website[Website]
    Pipeline[Pipeline]
  end

  Sponsor((Sponsor))
  Teacher((Teacher))
  Student((Student))
  Engineer((Engineer))

  Student --> |studies| Website
  Student --> |loves| Sponsor
  Student --> |respects| Teacher
  Student --> |complements| Draft
  Teacher -.- Engineer
  Sponsor --> |feeds| Teacher
  Sponsor --> |feeds| Engineer
  Teacher --> |reviews| Draft
  File --> |triggers| Pipeline
  Draft -.- File
  Pipeline --> |updates| Website
  Teacher --> |authors| File
  Engineer --> |specifies| File
  Engineer --> |maintains| Pipeline
  Engineer --> |hosts| Website
```