doc: reorganize whole contribution section in a clearier way

OpenRailAssociation · Feb 6, 2024 · a649121 · a649121
1 parent c7a9658
commit a649121
Show file tree

Hide file tree

Showing 41 changed files with 796 additions and 543 deletions.
diff --git a/content/docs/guides/contribute/_index.en.md b/content/docs/guides/contribute/_index.en.md
@@ -4,26 +4,3 @@ linkTitle: "Contribute to OSRD"
 weight: 10
 description: Learn about the how we work, and how you can work with us
 ---
-
-First off, thanks for taking the time to contribute!
-
-The following chapters are a set of guidelines for contributing to OSRD[^guidelines-not-rules]. If you have already contributed to open source projects before, you probably won't be surprised.
-If you have not, it will probably help a lot!
-
-### Communicate
-
-Chatting with other contributors is a great way to speed things up:
-
-- Join our instant messaging room on IRC at [libera.chat#osrd](https://web.libera.chat/#osrd)
-- [**Create an issue**](https://github.com/osrd-project/osrd/issues/new/choose) to discuss your contribution project
-
-### Inquire
-
-Just like with any project, changes rely on past work.
-Before making changes, it is best to learn about what's already there:
-
-- [read technical documentation]({{< ref "/docs" >}})
-- read the existing source code related to your project
-- chat with developers who last worked on areas you are interested in
-
-[^guidelines-not-rules]: These guidelines are mostly not strict rules, it's probably fine to do things slightly differently.
diff --git a/content/docs/guides/contribute/_index.fr.md b/content/docs/guides/contribute/_index.fr.md
@@ -4,23 +4,3 @@ linkTitle: "Contribuer à OSRD"
 weight: 10
 description: Comment apporter sa pierre à l'édifice
 ---
-
-Déjà, merci d'avoir pris le temps de contribuer !
-
-Si les sections suivantes forment un guide du contributeur, ce n'est pas pour autant un ensemble de règles strictes. En fait, si vous avez déjà contribué à des gros projets opensource, la suite ne sera pas surprenante. Dans le cas contraire, elle vous sera probablement très utile !
-
-### Communiquer
-
-Vous pouvez gagner du temps en discutant de votre projet de contribution avec les autres contributeurs :
-
-- Rejoignez le salon de messagerie instantanée sur IRC à [libera.chat#osrd](https://web.libera.chat/#osrd)
-- [**Créez une issue**](https://github.com/osrd-project/osrd/issues/new/choose) pour avoir un endroit un discuter de votre contribution
-
-### Se renseigner
-
-Comme dans tout projet, chaque changement se repose sur ce qui a été fait par le passé.
-Avant d'apporter un changement, renseignez-vous sur l'existant :
-
-- Vous pouvez [lire la documentation technique]({{< ref "/docs" >}})
-- Il est préférable de lire le code source de l'application en rapport avec votre projet
-- Vous pouvez contacter les derniers développeurs à avoir travaillé sur les zones du code en rapport avec votre projet
diff --git a/content/docs/guides/contribute/batch-updating-dependencies.en.md b/content/docs/guides/contribute/batch-updating-dependencies.en.md
diff --git a/content/docs/guides/contribute/batch-updating-dependencies.fr.md b/content/docs/guides/contribute/batch-updating-dependencies.fr.md
diff --git a/content/docs/guides/contribute/bug-reports.en.md b/content/docs/guides/contribute/bug-reports.en.md
@@ -1,7 +1,7 @@
 ---
 title: "Report issues"
 linkTitle: "Report issues"
-weight: 20
+weight: 5
 description: "Report a bug or suggest an enhancement"
 ---
 

diff --git a/content/docs/guides/contribute/bug-reports.fr.md b/content/docs/guides/contribute/bug-reports.fr.md
@@ -1,7 +1,7 @@
 ---
 title: "Signaler des problèmes"
 linkTitle: "Signaler des problèmes"
-weight: 20
+weight: 5
 description: "Comment signaler un bug ou suggérer une amélioration"
 ---
 

diff --git a/content/docs/guides/contribute/code-review.en.md b/content/docs/guides/contribute/code-review.en.md
@@ -0,0 +1,20 @@
+---
+title: "Review process"
+linkTitle: "Review process"
+description: "How to give useful feedback"
+weight: 4
+---
+
+The reviewer/maintainer undertakes to carry out the review quickly, and is also responsible for closing _request changes_, check commit history and quickly merge the _pull request_ if allowed.
+
+We propose you a few tips and recommendations that we think are relevant to a human, relevant and rewarding code review for all contributors:
+- [How to Make Your Code Reviewer Fall in Love with You?](https://mtlynch.io/code-review-love/) by Michael Lynch.
+- [How to Do Code Reviews Like a Human? ](https://mtlynch.io/human-code-reviews-1/) by Michael Lynch.
+
+{{% include "./review-process.en.md" %}}
+
+> If the reviewer is not maintainer, the PR's author has the responsability to contact a maintainer to merge the PR. In special cases (especially near feature freeze), maintainer should be found early.
+
+## The code review pyramid
+
+{{< figure src="/images/docs/contribute/code_review_pyramid.svg" link="https://www.morling.dev/blog/the-code-review-pyramid/">}}
diff --git a/content/docs/guides/contribute/code-review.fr.md b/content/docs/guides/contribute/code-review.fr.md
@@ -0,0 +1,20 @@
+---
+title: "Revue de code"
+linkTitle: "Revue de code"
+description: "Comment faire des retours constructifs"
+weight: 4
+---
+
+Le reviewer/mainteneur s'engage à effectuer la revue de code rapidement, c'est aussi à lui qu'appartient de fermer les « _request changes_ », de bien vérifier l'historique des commits, et de fusionner la « _pull request_ » s'il en a les droits.
+
+Nous vous soumettons quelques conseils et recommandations qui nous semblent pertinentes pour une revue de code humaine, pertinente et enrichissante pour tous ses contributeurs :
+- [How to Make Your Code Reviewer Fall in Love with You?](https://mtlynch.io/code-review-love/) par Michael Lynch.
+- [How to Do Code Reviews Like a Human? ](https://mtlynch.io/human-code-reviews-1/) par Michael Lynch.
+
+{{% include "./review-process.fr.md" %}}
+
+> Si la personne qui fait la revue de code n'est pas mainteneur, c'est à l'auteur de PR de trouver un mainteneur pour pouvoir fusionner sa PR avec le code. Dans certains cas particuliers (notamment juste avant le gel des fusions en fin d'itération), le mainteneur doit être averti plus tôt.
+
+## La pyramide de la revue de code
+
+{{< figure src="/images/docs/contribute/code_review_pyramid.svg" link="https://www.morling.dev/blog/the-code-review-pyramid/">}}
diff --git a/content/docs/guides/contribute/code-reviews/index.en.md b/content/docs/guides/contribute/code-reviews/index.en.md
diff --git a/content/docs/guides/contribute/code-reviews/index.fr.md b/content/docs/guides/contribute/code-reviews/index.fr.md
diff --git a/content/docs/guides/contribute/code.en.md b/content/docs/guides/contribute/code.en.md
diff --git a/content/docs/guides/contribute/code.fr.md b/content/docs/guides/contribute/code.fr.md
diff --git a/content/docs/guides/contribute/contribute-code/_index.en.md b/content/docs/guides/contribute/contribute-code/_index.en.md
@@ -0,0 +1,10 @@
+---
+title: "Contribute code"
+linkTitle: "Contribute code"
+weight: 3
+description: "Integrate changes into OSRD"
+---
+
+This chapter is about the process of integrating changes into the common code base. **If you need help at any stage, open an issue or message us.**
+
+OSRD application is split in multiple services written in several languages. We try to follow general code best practices and follow each language specificities when required.