Déjà, merci de considérer de contribuer au site Ressources de Women On Rails. C'est grâce à toi que le site reste pertinent pour toutes ses utilisatrices et tous ses utilisateurs !
Ce fichier a pour but de t'aider à faire en sorte que ta contribution (que ce soit ta première sur un repo en open source ou pas) se passe bien, pour toi comme pour les personnes qui gèrent le site.
C'est un site de ressources, donc tu peux faire des contributions de contenu. On a:
- les pages ressources où tu peux modifier / ajouter des pages ou même des catégories
- le blog où tu peux poster un article
Mais tu peux aussi contribuer autrement :
- sur toute la documentation du repository (le readme, ce fichier, le code of conduct...)
- la mise en page ou le design du site
- signaler un bug
- rajouter des outils sur le repo: un linter pour le MarkDown, une CI, une librairie cool pour les projets open-source comme all-contributors...
- Si tu veux ajouter une nouvelle page sur le site (qui n'est pas une page ressource ou un article de blog) ou corriger un bug, commence par créer une issue pour qu'on valide ça ensemble.
- Women On Rails suit le code of conduct de Contributor Covenant, donc en communiquant avec l'ensemble de la communauté (les personnes gérants le repo, les personnes qui contribuent) tu dois respecter ces règles.
- Si tu contribues du contenu, il faut également qu'il respecte ces règles de conduite, sinon ta contribution sera refusée.
- Les textes doivent être inclusifs. Ça donne:
Salut les contributeurs et les contributricesplutôt que justeSalut les contributeurs. - Pour ce qui est de la production de contenu sur le site ou le blog, on fait attention à ce qu'il n'y ait pas de fautes, donc on te demandera de reprendre ton texte s'il y en a (en t'aidant hein).
- Le site est ouvert à tout le monde et toute contribution respectant les règles est la bienvenue. Pour le blog, on n'accepte des articles que de femmes membres de Women On Rails, c'est un endroit réservé où faire entendre nos voix et être inspirées.
Bon, maintenant, par où tu peux commencer ?
Tu peux déjà regarder s'il y a des issues ouvertes avec le label good-first-issues, qui sont facilement accessibles pour les débutantes ou débutants en open source, histoire de briser la glace en douceur !
Quand tu vois une issue qui t'intéresse et dont personne ne s'occupe, commente en disant que tu souhaites la faire et tu peux commencer à coder !
Tu peux aussi directement proposer une modification sur une des pages déjà en ligne.
Dans la section projects il y a l'avancement des pages qu'on souhaite rajouter sur le site:
- Si tu en vois qui t'intéressent, créé une issue avec la ou les pages que tu souhaites écrire pour pas que tout le monde l'écrive en même temps et peut-être même demander de l'aide ou collaborer :)
- Si tu as une idée de page qui n'est pas marquée, fais une issue pour proposer un sujet.
Si tu n'as jamais fait de Pull Request auparavant, tu peux t'entraîner ici.
Si tu t'es déjà baladé·e sur le site, tu as pu voir qu'en bas de chaque page ressource il y a ce lien:
Si tu remarques que quelque chose ne va pas sur la page ou si tu veux y ajouter ta contribution:
- Clique sur le lien
Edit this page - GitHub te propose de forker le repo (c'est-à-dire copier une version du dossier sur ton compte)
- Modifie le fichier directement en ligne
- Commite en cliquant sur
Propose change
- Tu arrives sur une page qui te propose de faire ta Pull Request. Clique sur
Create Pull Request
Si tu préfères travailler de ton éditeur de texte:
- Forke le repo
- Clone ton repo
- Installe le site
- Créé une branche
git checkout -b nom-branche - Fais tes changements et commite
- Pushe
- Retourne sur la page de ce repo
- Fais une Pull Request
Si tu es un plus aguerri·e (ou pressé·e) et que tes modifications ou ajout ne concernent qu'un seul fichier:
- Forke le repo
- Modifie ou ajoute directement des fichiers en ligne
- Commite
- Retourne sur la page de ce repo
- Fais une Pull Request
Modifier un fichier en cliquant sur le petit crayon en haut:
Ajouter un fichier:
$ yarn- Lance le serveur local:
$ yarn startCela va t'ouvrir une page http://localhost:3000/
Quand tu crées ta Pull Request, tu auras automatiquement un template à remplir pour décrire tes changements.
Tu peux l'écrire soit en anglais soit en français, comme tu préfères.
Décris ce que tu as fait, si ça concerne du design, c'est bien de mettre une image avant/après.
Voici un exemple de pull request qui a été mergée.
N'oublie pas de faire le lien vers l'issue s'il y en a une.
Quand tu crées une issue, on te propose automatiquement un template pour signaler un bug ou proposer une feature.
Le site est construit en utilisant la version 2 de Docusaurus, qui permet de mettre facilement en ligne de la documentation.
Il y a quelques pages en React (la page d'accueil, la page à propos), mais sinon les fichiers ressources et les pages de blog sont au format MarkDown, comme celui de tout README d'un repo.
Tu peux réviser la syntaxe Markdown en 60 secondes ou suivre un tutorial de 10 minutes.
Il y a aussi quelques pages avec des éléments plus design où il y a du React dans du MarkDown, c'est le format MDX (🤯) mais tu n'es pas du tout obligé·e de le connaître pour contribuer.
Tu trouves dans website/blog les articles et dans website/docs les pages du site dans des sous-dossiers.
Les fichiers images sont dans website/src/assets/img et tu peux ajouter du css custom dans website/src/assets/css/custom.css.
La barre de navigation sur le côté est dans le fichier website/src/sidebar.js.
website/
docs/
dossier/
doc-1.md
doc-2.md
doc-3.md
website/
blog/
2016-3-11-oldest-post.md
2017-10-24-newest-post.md
core/
node_modules/
pages/
src/
assets/
css/
img/
sidebars.js
package.json
docusaurus.config.js
Comment éditer une page doc existante
Tu peux modifier une page en te rendant dans le dossier website/docs et en modifiant le document que tu veux:*Fichier website/docs/document-a-modifier.md*
---
id: document-à-modifier
title: Document à modifier
---
À modifier...Comment éditer un article de blog existant
Tu peux modifier une page en te rendant dans le dossier website/blog et en modifiant l'article que tu veux:*Fichier website/blog/article-a-modifier.md*
---
id: article-a-modifier
title: Article à modifier
---
À modifier...Ajouter une nouvelle page doc
- Ajoute un nouveau document au format markdown dans le dossier website/docs, comme par exemple:
*Fichier website/docs/nouveau-doc.md*
---
id: nouveau-doc
title: Nouveau doc
---
Nouveau contenu.
Nouvelle vie.- Rajoute l'ID de ce doc dans le fichier de la barre de navigation, soit en l'ajoutant directement dans une catégorie existante (ici: Bienvenue):
/* Fichier website/src/sidebars.js */
{
"docs": {
"Bienvenue": [
"start",
"nouveau-doc" // ajoute ton doc ici
],
...
},
...
}- Tu peux aussi créer ta propre catégorie sous le format:
{
"docs": {
"Nouvelle catégorie": [
"nouveau-doc"
],
...
},
...
}Ajouter un nouvel article de blog
Ajoute un article avec le formatYYYY-MM-DD-Le-Titre-De-Mon-Article.md
dans website/blog:
*Fichier website/blog/2020-10-03-It-s-October-Third.md*
---
author: Foo Bar
authorURL: https://twitter.com/foobarbaz
authorFBID: 503283835
title: It's October Third
---
Lorem Ipsum...L'aperçu de l'article doit se situer au-dessus de la ligne truncate
// Haut de l'article
<!--truncate-->
// Suite de l'articleAjouter des éléments à la barre de navigation du haut
Tu peux ajouter des liens vers les documents, des pages customs ou vers des sites externes en modifiant la clé headerLinks du fichier website/docusaurus.config.js:/* Fichier website/docusaurus.config.js */
{
headerLinks: [
...
/* ajouter un doc */
{ doc: 'exemples', label: 'Exemples' },
/* ajouter une page custom */
{ page: 'Aide', label: 'Aide' },
/* ajouter un site externe */
{ href: 'https://github.com/facebook/docusaurus', label: 'GitHub' },
...
],
...
}Ajouter une page custom
Docusaurus utilise les React components pour construire des pages. Les pages sont sauvegardés au format .js dans website/src/pages.Tu peux directement ajouter du html dans les fichiers au format .md ou mdx.
On utilise le thème d'Infima, ils ont déjà un système de grid défini et de nombreux éléments et classes css.
Pour tout ce qui concerne les components, nous avons créé une documentation où sont listés tous les components disponibles, comment les utiliser et comment en créer :
Docusaurus a une documentation très détaillée pour tout ce qui est création de page, ajout de style... N'hésite pas à t'y référer, en particulier la section Guides.
Pfiouuu, ça y est, tu as fais une Pull Request, maintenant qu'est-ce qu'il va se passer ?
Tu as normalement une réponse dans les 48 heures, si ce n'est pas le cas, tu peux taguer dans la Pull Request: @AJuliette (pour l'instant je suis la seule mainteneuse du repo).
Le déploiement est actuellement manuel, il est fait après chaque Pull Request mergée, donc tu verras tes changements rapidement (et tu seras prévenu·e) !
Si tu traites une issue, tu peux reprendre son nom. Par exemple pour mettre à jour la doc pour l'open source j'ai une branche prepare-repo-for-contributions.
Si tu ajoutes une page ou un article ça peut être: add-page-nom-de-la-page / add-blog-post-nom-ou-sujet-de-l'article.
Même chose si tu modifies une ressource: update-page-nom-de-la-page / update-blog-post-nom-ou-sujet-de-l'article.
On n'a pas de convention particulière, fais comme tu as l'habitude.
- Pour les issues simples:
good first issue. - Pour celles qui ont besoin d'être redéfinies et d'aide dans la conception:
en cours d'écriture. - Pour les bug fixes:
bug.