Aller au contenu principal

Contribuer à la documentation du SophiaHackLab

Bienvenue dans le dépôt de documentation du SophiaHackLab!

Sommaire​

Démarrage rapide​

Option 1: Contribution depuis le navigateur (recommandé pour les petites modifications)​

Pas d'installation requise! Contribuez directement depuis votre navigateur.

Éditer une page existante:

  1. Cliquez sur "Modifier cette page" en bas de n'importe quelle page de documentation
  2. Éditez le fichier Markdown dans l'éditeur GitHub
  3. Proposez vos changements via une pull request

Ajouter un nouveau fichier:

  1. Visitez le dépôt GitHub
  2. Naviguez vers docs/ ou un sous-dossier de projet
  3. Cliquez sur "Add file" > "Create new file"
  4. Rédigez votre contenu et créez une pull request

Option 2: Configuration de développement local (pour les modifications complexes)​

Prérequis:

  • Node.js 20+
  • npm 10+
  • Git
  • Connaissance de base de Markdown

Installation rapide:

# Cloner et installer
git clone https://github.com/SophiaHackLab/docusaurus.git
cd docusaurus
npm install

# Installer les navigateurs pour les tests
npx playwright install --with-deps

# Démarrer le développement
npm start

Le site s'ouvre à http://localhost:3000 avec rechargement automatique.

Configuration de développement​

Workflow de développement​

1. Développement local avec rechargement automatique:

npm start  # Le site s'ouvre à http://localhost:3000

2. Construction et prévisualisation de production:

npm run build    # Construire le site
npm run serve    # Servir la construction de production

3. Tests (REQUIS avant toute PR):

npm run test:local   # Suite complète: build + tests sur 3 navigateurs
npm run test:report  # Voir le rapport HTML des tests

Configuration des tests Playwright​

Notre suite de tests contient 23 tests qui s'exécutent sur 3 navigateurs (Chromium, Firefox, WebKit), soit 69 exécutions au total.

Navigateurs Playwright:

npx playwright install --with-deps

Exigences de test:

  • ✅ Tous les tests doivent passer (23 tests × 3 navigateurs = 69 exécutions)
  • ✅ Tests réussis sur les 3 navigateurs (Chromium, Firefox, WebKit)
  • ✅ Construction sans erreur
  • ✅ Aucun lien brisé

Rapports générés:

  • HTML interactif: test-results/html/index.html
  • JUnit XML: test-results/junit.xml
  • Captures d'écran des échecs

Commandes courantes​

# Développement
npm start              # Serveur de développement
npm run build          # Construction de production
npm run serve          # Servir la construction

# Tests
npm run test:local     # Suite complète (recommandé)
npm run test:e2e       # Tests e2e uniquement
npm run test:report    # Ouvrir le rapport HTML

# Maintenance
npm run clear          # Vider le cache
npm install            # Mettre à jour les dépendances

Guide de contribution​

Types de contributions​

  • 📝 Documentation - Corriger, clarifier, ajouter des exemples
  • ✍️ Blog - Rédiger des articles, tutoriels, actualités
  • 🎯 Projets - Ajouter ou mettre à jour la documentation de projet
  • ✨ Fonctionnalités - Améliorer le site
  • 🐛 Corrections - Liens brisés, formatage, fautes de frappe
  • 🧪 Tests - Ajouter ou améliorer la couverture de tests
  • 🎨 Design - Améliorer le style et l'UX

Workflow de contribution​

Étapes de contribution​

1. Créer une branche:

git checkout -b feature/descriptive-name

2. Effectuer vos modifications:

  • Fichiers markdown: docs/
  • Images: static/img/
  • Configuration: docusaurus.config.ts

3. Tester localement:

npm start              # Prévisualiser les changements
npm run test:local     # Exécuter tous les tests

4. Commit et push:

git add .
git commit -m "Description concise des changements"
git push origin feature/descriptive-name

5. Créer une Pull Request:

  • Ouvrir une PR sur GitHub
  • Remplir le modèle de description
  • Attendre la revue de code et l'approbation

Synchronisation avec main​

Avant de créer une PR, synchronisez avec la branche principale:

git checkout main
git pull origin main
git checkout your-branch
git rebase main

Contribuer au blog​

Le blog du SophiaHackLab est un espace pour partager des actualités, des tutoriels, des retours d'expérience et des annonces liées à notre communauté.

Créer un article de blog​

1. Structure d'un article:

Créez un fichier dans blog/ avec le format: YYYY-MM-DD-titre-article.md

---
slug: titre-court-url
title: Titre complet de l'article
authors: [nom_auteur]
tags: [tag1, tag2, tag3]
date: 2025-01-15
---

Résumé court de l'article visible dans la liste. Cette première section s'affiche comme aperçu.

<!--truncate-->

Le contenu complet de l'article commence ici après le marqueur `<!--truncate-->`.

## Section 1
Votre contenu...

## Section 2
Plus de contenu...

2. Configurer votre profil d'auteur:

Ajoutez votre profil dans blog/authors.yml:

nom_auteur:
  name: Prénom Nom
  title: Votre titre/rôle
  url: https://votre-site.com  # optionnel
  image_url: /img/authors/votre-photo.jpg  # optionnel
  email: votre@email.com  # optionnel
  socials:
    github: votre-username  # optionnel
    twitter: votre-handle  # optionnel
    linkedin: votre-profile  # optionnel

3. Gérer les tags:

Les tags permettent de catégoriser les articles. Ajoutez-les dans blog/tags.yml:

nouveau-tag:
  label: "Libellé du Tag"
  description: "Description du tag pour le SEO"
  permalink: "/nouveau-tag"  # optionnel

Tags existants: événements, projets, communauté, tutoriel, actualités, open-source, rust, etc.

Bonnes pratiques pour les articles​

Contenu:

  • Titre clair et descriptif (50-60 caractères max)
  • Résumé engageant avant <!--truncate-->
  • Structure avec des titres H2/H3 pour faciliter la navigation
  • Contenu de qualité, bien relu et sans fautes
  • Exemples de code avec coloration syntaxique

Images:

  • Placez les images dans static/img/blog/YYYY/nom-article/
  • Utilisez des images optimisées (compression, taille appropriée)
  • Référencez: ![Description](/img/blog/2025/nom-article/image.jpg)
  • Ajoutez toujours un texte alternatif descriptif

SEO et métadonnées:

  • Slug court et descriptif
  • Tags pertinents (3-5 maximum)
  • Description/résumé captivant

Exemples d'articles:

  • Annonces d'événements
  • Tutoriels techniques
  • Retours sur des projets
  • Actualités de la communauté
  • Guides et how-tos

Workflow de publication​

1. Créer et prévisualiser:

# Créer votre article
touch blog/2025-01-15-titre-article.md

# Démarrer le serveur de développement
npm start

# Accéder au blog: http://localhost:3000/blog

2. Tester:

# Vérifier que les tests passent (incluant les tests de blog)
npm run test:local

3. Soumettre:

  • Créer une branche: git checkout -b blog/titre-article
  • Commit: git commit -m "blog: ajouter article sur [sujet]"
  • Push et créer une Pull Request

4. Publication: Une fois la PR approuvée et fusionnée, l'article sera automatiquement déployé sur le site.

Ajouter de nouveaux projets​

Structure requise​

Chaque projet doit inclure deux fichiers dans docs/projects/nom-projet/:

1. README.md - Documentation principale:

# Nom du projet

## Aperçu
Description courte du projet.

## Description
Détails, objectifs, état actuel.

## Technologies
Outils et frameworks utilisés.

## Équipe
Responsables et contributeurs principaux.

## S'impliquer
Comment rejoindre et contribuer.

## Ressources
Liens vers dépôts, docs, ressources externes.

## Contact
Coordonnées de l'équipe.

2. CONTRIBUTING.md - Guide de contribution:

# Contribuer à [Nom du projet]

## Configuration
Instructions d'installation et de configuration.

## Structure
Organisation des fichiers et répertoires.

## Standards
Conventions de code et pratiques.

## Tests
Procédures de test spécifiques.

Étapes de création​

1. Créer le répertoire:

mkdir -p docs/projects/nom-projet

2. Créer les fichiers requis (README.md et CONTRIBUTING.md)

3. Vérifier l'affichage:

npm start  # Vérifier que le projet apparaît dans la barre latérale

4. Ajouter des tests dans tests/projects.spec.ts:

test('should load Nom Project page', async ({ page }) => {
  await page.goto('/docs/projects/nom-projet');
  await expect(page).toHaveTitle(/Nom Project/);
  const mainContent = page.locator('article, main').first();
  await expect(mainContent).toBeVisible();
});

Standards de documentation​

Conventions Markdown​

Structure:

  • Langage clair et concis
  • Titres hiérarchiques: H1 (titre), H2 (sections), H3 (sous-sections)
  • Listes pour les étapes et points
  • Images dans static/img/ (utilisez avec parcimonie)

Code:

# Toujours spécifier le langage pour la coloration syntaxique
npm install

# Ajouter des commentaires pour le code complexe
npm start  # Démarre le serveur de développement

Liens:

  • Internes: chemins relatifs [Projet](../projects/rov/README.md)
  • Externes: URLs absolues [Docusaurus](https://docusaurus.io/)

Nomenclature​

  • Répertoires: minuscules-avec-tirets (nom-projet)
  • Fichiers standards: MAJUSCULES (README.md, CONTRIBUTING.md)
  • Autres fichiers: minuscules-descriptifs (guide-installation.md)

Frontmatter​

Configurez les métadonnées de page:

---
sidebar_position: 1
title: Titre personnalisé
description: Description SEO
---

Processus de Pull Request​

Avant de créer une PR​

  1. Synchronisez avec la branche main:

    git checkout main
    git pull origin main
    git checkout your-branch
    git rebase main

  2. Exécutez les tests localement:

    npm run test:local

  3. Révisez vos modifications:

    git diff main

Créer une Pull Request​

  1. Poussez votre branche:

    git push origin your-branch

  2. Ouvrez une PR sur GitHub:

    • Cliquez sur "New Pull Request"
    • Sélectionnez main comme branche de base
    • Sélectionnez votre branche comme branche de comparaison

  3. Remplissez le modèle de PR:

    • Titre: Résumé clair et descriptif
    • Description: Quelles modifications vous avez effectuées et pourquoi
    • Tests: Confirmez que vous avez exécuté les tests localement
    • Captures d'écran: Ajoutez si vous avez modifié l'UI/le style

  4. Soumettez pour révision

Exigences de PR​

Votre PR doit:

  • ✅ Réussir tous les tests automatisés (GitHub Actions)
  • ✅ Avoir une description claire
  • ✅ Référencer les issues liées (le cas échéant)
  • ✅ Suivre les standards de documentation
  • ✅ Ne pas introduire de liens brisés
  • ✅ Se construire avec succès

Processus de révision​

  1. Vérifications automatisées exécutées via GitHub Actions:

    • Vérification de la construction
    • Tests E2E (23 tests sur 3 navigateurs = 69 exécutions)
    • Génération de rapports de test (JUnit XML et HTML)

  2. Révision manuelle par les mainteneurs:

    • Qualité du code
    • Clarté de la documentation
    • Cohérence avec les standards du projet

  3. Incorporation des retours:

    • Répondez aux commentaires de révision
    • Poussez les mises à jour vers votre branche
    • Demandez une nouvelle révision

  4. Fusion:

    • Une fois approuvé, votre PR sera fusionnée
    • Le site sera automatiquement déployé sur GitHub Pages

Code de conduite​

Nos valeurs​

En tant que hackerspace collaboratif, SophiaHackLab valorise:

  • Inclusivité - Accueillir les personnes de tous horizons
  • Respect - Traiter tout le monde avec gentillesse et considération
  • Collaboration - Travailler ensemble, partager les connaissances
  • Créativité - Encourager l'expérimentation et l'innovation
  • Ouverture - Partager les idées et les ressources librement

Comportement attendu​

  • Soyez respectueux et attentionné dans toutes les interactions
  • Fournissez des retours constructifs
  • Aidez les autres à apprendre et à grandir
  • Créditez les autres pour leurs contributions
  • Accueillez les nouveaux venus et aidez-les à démarrer

Comportement inacceptable​

  • Harcèlement ou discrimination de toute nature
  • Commentaires irrespectueux ou inflammatoires
  • Attaques personnelles ou trolling
  • Publication d'informations privées d'autrui
  • Autre conduite inappropriée pour un cadre professionnel

Signalement de problèmes​

Si vous vivez ou êtes témoin d'un comportement inacceptable:

  • Contact: crew@shl.contact
  • Les mainteneurs examineront et prendront les mesures appropriées
  • Tous les signalements seront traités de manière confidentielle

Ressources et aide​

Documentation du projet​

Documentation externe​

Support​

Questions sur la documentation:

Problèmes techniques:

  • Issues GitHub existantes
  • DEPLOYMENT.md
  • Documentation Docusaurus

À propos du SophiaHackLab:

Structure du projet​

docusaurus/
├── .github/
│   └── workflows/          # CI/CD GitHub Actions pour tests et déploiement
├── blog/                   # Articles de blog
│   ├── *.md                # Articles au format Markdown (YYYY-MM-DD-titre.md)
│   ├── authors.yml         # Définition des auteurs du blog
│   └── tags.yml            # Définition des tags pour catégoriser les articles
├── docs/                   # Documentation principale
│   ├── intro.md            # Page d'accueil de la documentation
│   ├── contributing.md     # Ce fichier - guide de contribution
│   └── projects/           # Documentation des projets du SophiaHackLab
│       ├── rov/            # Projet Underwater ROV
│       ├── fete_de_la_science/  # Fête de la Science
│       └── triviak/        # Projet Triviak
├── src/                    # Code source personnalisé
│   ├── components/         # Composants React réutilisables
│   ├── css/                # Styles CSS personnalisés
│   └── pages/              # Pages React personnalisées (/, /about, etc.)
├── static/                 # Ressources statiques
│   ├── img/                # Images et icônes du site
│   └── test-reports/       # Rapports de tests générés
├── tests/                  # Suite de tests E2E
│   ├── accessibility.spec.ts    # Tests d'accessibilité
│   ├── blog.spec.ts            # Tests du blog
│   ├── homepage.spec.ts        # Tests de la page d'accueil
│   ├── navigation.spec.ts      # Tests de navigation
│   └── projects.spec.ts        # Tests des pages projet
├── build/                  # Site généré (production)
├── .docusaurus/            # Cache et fichiers temporaires
├── docusaurus.config.ts    # Configuration principale du site
├── playwright.config.ts    # Configuration des tests E2E
├── sidebars.ts             # Configuration de la barre latérale
├── tsconfig.json           # Configuration TypeScript
└── package.json           # Dépendances npm et scripts

Description des répertoires clés​

📝 Blog (blog/)

  • Articles de blog au format Markdown
  • Nommage: YYYY-MM-DD-titre-de-l-article.md
  • Fichiers de configuration:
    • authors.yml - Profils des auteurs (nom, titre, réseaux sociaux)
    • tags.yml - Tags pour catégoriser les articles
  • Frontmatter requis: title, slug, authors, tags, date
  • Visible à l'URL /blog sur le site

📚 Documentation (docs/)

  • intro.md - Page d'accueil de la section documentation
  • contributing.md - Guide de contribution (ce fichier)
  • projects/ - Un sous-dossier par projet avec README.md et CONTRIBUTING.md
  • Organisation automatique dans la barre latérale
  • Visible à l'URL /docs sur le site

⚛️ Code source (src/)

  • components/ - Composants React réutilisables (header, footer, cards, etc.)
  • pages/ - Pages personnalisées non générées par Docusaurus
  • css/ - Feuilles de style CSS globales et personnalisées

🖼️ Ressources statiques (static/)

  • Tous les fichiers servis tels quels (pas de traitement)
  • img/ - Logos, icônes, images du site
  • Accessible via l'URL /img/fichier.png

🧪 Tests (tests/)

  • Tests E2E avec Playwright
  • 23 tests × 3 navigateurs = 69 exécutions totales
  • Tests de navigation, accessibilité, blog, projets, etc.

Référence rapide​

Commandes npm:

npm start          # Dev server
npm run build      # Production build
npm run serve      # Serve build
npm run test:local # Tests complets
npm run test:report # Rapport HTML
npm run clear      # Vider cache

Commandes Git:

git checkout -b feature/nom    # Créer branche
git add . && git commit -m ""  # Commit
git push origin feature/nom    # Push
git checkout main && git pull  # Sync main
git rebase main                # Rebase sur main

Merci de contribuer au SophiaHackLab! 🚀

Liens utiles: Site web | Dépôt GitHub | Site de documentation