AGENTS.md

1# AGENTS.md
2 
3## Présentation du projet
4 
5Il s'agit d'un référentiel de programme éducatif pour enseigner les fondamentaux du développement web aux débutants. Le programme est un cours complet de 12 semaines développé par les Microsoft Cloud Advocates, comprenant 24 leçons pratiques couvrant JavaScript, CSS et HTML.
6 
7### Composants clés
8 
9- **Contenu éducatif** : 24 leçons structurées organisées en modules basés sur des projets  
10- **Projets pratiques** : Terrarium, Jeu de frappe, Extension de navigateur, Jeu spatial, Application bancaire, Éditeur de code, et Assistant de chat IA  
11- **Quiz interactifs** : 48 quiz avec 3 questions chacun (évaluations pré/post- leçon)  
12- **Support multilingue** : Traductions automatiques en 50+ langues via GitHub Actions  
13- **Technologies** : HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (pour projets IA)  
14 
15### Architecture
16 
17- Référentiel éducatif avec structure basée sur les leçons  
18- Chaque dossier de leçon contient README, exemples de code, et solutions  
19- Projets indépendants dans des répertoires séparés (quiz-app, divers projets de leçons)  
20- Système de traduction utilisant GitHub Actions (co-op-translator)  
21- Documentation servie via Docsify et disponible en PDF  
22 
23## Commandes d'installation
24 
25Ce référentiel est principalement destiné à la consommation de contenu éducatif. Pour travailler avec des projets spécifiques :
26 
27### Installation du référentiel principal
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Installation de l'application Quiz (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Démarrer le serveur de développement
40npm run build      # Construire pour la production
41npm run lint       # Exécuter ESLint
42```
43 
44### API du projet bancaire (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Démarrer le serveur API
50npm run lint       # Exécuter ESLint
51npm run format     # Formater avec Prettier
52```
53 
54### Projets d'extension de navigateur
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Suivez les instructions spécifiques au navigateur pour le chargement des extensions
60```
61 
62### Projets de jeu spatial
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Ouvrez index.html dans un navigateur ou utilisez Live Server
68```
69 
70### Projet de chat (Backend Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Définir la variable d'environnement GITHUB_TOKEN
76python api.py
77```
78 
79## Flux de développement
80 
81### Pour les contributeurs de contenu
82 
831. **Forkez le référentiel** vers votre compte GitHub  
842. **Clonez votre fork** localement  
853. **Créez une nouvelle branche** pour vos modifications  
864. Modifiez le contenu des leçons ou les exemples de code  
875. Testez les modifications de code dans les répertoires de projets concernés  
886. Soumettez des pull requests en suivant les consignes de contribution  
89 
90### Pour les apprenants
91 
921. Forkez ou clonez le référentiel  
932. Naviguez dans les dossiers de leçons dans l'ordre  
943. Lisez les fichiers README pour chaque leçon  
954. Complétez les quiz pré-leçon sur https://ff-quizzes.netlify.app/web/  
965. Travaillez les exemples de code dans les dossiers de leçons  
976. Réalisez les devoirs et défis  
987. Passez les quiz post-leçon  
99 
100### Développement en direct
101 
102- **Documentation** : Lancez `docsify serve` à la racine (port 3000)  
103- **Application Quiz** : Lancez `npm run dev` dans le répertoire quiz-app  
104- **Projets** : Utilisez l’extension Live Server de VS Code pour les projets HTML  
105- **Projets API** : Lancez `npm start` dans les répertoires API concernés  
106 
107## Instructions de test
108 
109### Test de l'application Quiz
110 
111```bash
112cd quiz-app
113npm run lint       # Vérifier les problèmes de style de code
114npm run build      # Vérifier que la compilation réussit
115```
116 
117### Test de l'API bancaire
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Vérifiez les problèmes de style de code
122node server.js     # Vérifiez que le serveur démarre sans erreurs
123```
124 
125### Approche générale des tests
126 
127- Il s'agit d'un référentiel éducatif sans tests automatisés exhaustifs  
128- Les tests manuels portent sur :  
129  - Exécution des exemples de code sans erreurs  
130  - Fonctionnement correct des liens dans la documentation  
131  - Compilation réussie des projets  
132  - Respect des bonnes pratiques dans les exemples  
133 
134### Vérifications avant soumission
135 
136- Lancez `npm run lint` dans les dossiers contenant package.json  
137- Vérifiez la validité des liens markdown  
138- Testez les exemples de code dans le navigateur ou Node.js  
139- Vérifiez que les traductions conservent la structure appropriée  
140 
141## Directives de style de code
142 
143### JavaScript
144 
145- Utilisez la syntaxe moderne ES6+  
146- Respectez les configurations ESLint standard fournies dans les projets  
147- Utilisez des noms de variables et fonctions significatifs pour la clarté pédagogique  
148- Ajoutez des commentaires expliquant les concepts pour les apprenants  
149- Formatez avec Prettier si configuré  
150 
151### HTML/CSS
152 
153- Utilisez des éléments HTML5 sémantiques  
154- Appliquez des principes de design responsive  
155- Nommez clairement les classes  
156- Ajoutez des commentaires expliquant les techniques CSS pour les apprenants  
157 
158### Python
159 
160- Suivez les directives de style PEP 8  
161- Exemples de code clairs et pédagogiques  
162- Indications de type lorsque cela aide l'apprentissage  
163 
164### Documentation Markdown
165 
166- Hiérarchie claire des titres  
167- Blocs de code avec spécification du langage  
168- Liens vers des ressources complémentaires  
169- Captures d’écran et images dans les dossiers `images/`  
170- Texte alternatif pour les images pour l’accessibilité  
171 
172### Organisation des fichiers
173 
174- Leçons numérotées séquentiellement (1-getting-started-lessons, 2-js-basics, etc.)  
175- Chaque projet a les dossiers `solution/` et souvent `start/` ou `your-work/`  
176- Images stockées dans des dossiers `images/` spécifiques aux leçons  
177- Traductions dans la structure `translations/{code-langue}/`  
178 
179## Compilation et déploiement
180 
181### Déploiement de l'application Quiz (Azure Static Web Apps)
182 
183L'application quiz-app est configurée pour le déploiement avec Azure Static Web Apps :
184 
185```bash
186cd quiz-app
187npm run build      # Crée le dossier dist/
188# Déploie via le workflow GitHub Actions lors d'un push sur main
189```
190 
191Configuration Azure Static Web Apps :  
192- **Emplacement de l'application** : `/quiz-app`  
193- **Emplacement de sortie** : `dist`  
194- **Workflow** : `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`  
195 
196### Génération du PDF de documentation
197 
198```bash
199npm install                    # Installer docsify-to-pdf
200npm run convert               # Générer un PDF à partir de docs
201```
202 
203### Documentation Docsify
204 
205```bash
206npm install -g docsify-cli    # Installer Docsify globalement
207docsify serve                 # Servir sur localhost:3000
208```
209 
210### Builds spécifiques aux projets
211 
212Chaque répertoire de projet peut avoir son propre processus de build :  
213- Projets Vue : `npm run build` crée des bundles de production  
214- Projets statiques : Pas d'étape de build, fichiers servis directement  
215 
216## Directives pour les pull requests
217 
218### Format du titre
219 
220Utilisez des titres clairs et descriptifs indiquant la zone modifiée :  
221- `[Quiz-app] Ajout d’un nouveau quiz pour la leçon X`  
222- `[Lesson-3] Correction d’une faute dans le projet terrarium`  
223- `[Translation] Ajout de la traduction espagnole pour la leçon 5`  
224- `[Docs] Mise à jour des instructions d’installation`  
225 
226### Vérifications requises
227 
228Avant de soumettre une PR :  
229 
2301. **Qualité du code** :  
231   - Lancez `npm run lint` dans les répertoires de projet concernés  
232   - Corrigez toutes les erreurs et avertissements de lint  
233 
2342. **Vérification de build** :  
235   - Lancez `npm run build` si applicable  
236   - Assurez-vous qu’aucune erreur de build ne survient  
237 
2383. **Validation des liens** :  
239   - Testez tous les liens markdown  
240   - Vérifiez le bon fonctionnement des références aux images  
241 
2424. **Relecture du contenu** :  
243   - Corrigez l’orthographe et la grammaire  
244   - Assurez-vous que les exemples de code sont corrects et pédagogiques  
245   - Vérifiez que les traductions conservent le sens original  
246 
247### Exigences de contribution
248 
249- Acceptez la CLA Microsoft (vérification automatique à la première PR)  
250- Respectez le [Code de conduite open source Microsoft](https://opensource.microsoft.com/codeofconduct/)  
251- Consultez le [CONTRIBUTING.md](./CONTRIBUTING.md) pour les détails  
252- Référencez les numéros d’issues dans la description de la PR si applicable  
253 
254### Processus de relecture
255 
256- Les PR sont revues par les mainteneurs et la communauté  
257- La clarté pédagogique est priorisée  
258- Les exemples de code doivent suivre les bonnes pratiques actuelles  
259- Les traductions sont revues pour précision et adéquation culturelle  
260 
261## Système de traduction
262 
263### Traduction automatisée
264 
265- Utilise GitHub Actions avec le workflow co-op-translator  
266- Traduit automatiquement en 50+ langues  
267- Fichiers source dans les répertoires principaux  
268- Fichiers traduits dans `translations/{code-langue}/`  
269 
270### Ajout d’améliorations manuelles aux traductions
271 
2721. Localisez le fichier dans `translations/{code-langue}/`  
2732. Apportez des améliorations tout en préservant la structure  
2743. Assurez-vous que les exemples de code restent fonctionnels  
2754. Testez tout contenu de quiz localisé  
276 
277### Métadonnées des traductions
278 
279Les fichiers traduits incluent un en-tête de métadonnées :  
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Débogage et résolution de problèmes
293 
294### Problèmes courants
295 
296**L’application quiz ne démarre pas** :  
297- Vérifiez la version de Node.js (v14+ recommandé)  
298- Supprimez `node_modules` et `package-lock.json`, puis lancez `npm install` à nouveau  
299- Vérifiez les conflits de ports (par défaut : Vite utilise le port 5173)  
300 
301**Le serveur API ne démarre pas** :  
302- Vérifiez que Node.js est à la version minimale (node >=10)  
303- Vérifiez si le port est déjà utilisé  
304- Assurez-vous que toutes les dépendances sont installées via `npm install`  
305 
306**L’extension navigateur ne charge pas** :  
307- Vérifiez que manifest.json est bien formatté  
308- Consultez la console du navigateur pour les erreurs  
309- Suivez les instructions d’installation spécifiques au navigateur  
310 
311**Problèmes du projet chat Python** :  
312- Assurez-vous que le package OpenAI est installé : `pip install openai`  
313- Vérifiez que la variable d’environnement GITHUB_TOKEN est définie  
314- Vérifiez les autorisations d’accès aux modèles GitHub  
315 
316**Docsify ne sert pas la documentation** :  
317- Installez docsify-cli globalement : `npm install -g docsify-cli`  
318- Lancez depuis le répertoire racine du dépôt  
319- Vérifiez que `docs/_sidebar.md` existe  
320 
321### Conseils pour l’environnement de développement
322 
323- Utilisez VS Code avec l’extension Live Server pour les projets HTML  
324- Installez les extensions ESLint et Prettier pour un formatage cohérent  
325- Utilisez les DevTools du navigateur pour déboguer JavaScript  
326- Pour les projets Vue, installez l’extension Vue DevTools pour navigateur  
327 
328### Considérations de performance
329 
330- Le grand nombre de fichiers traduits (50+ langues) rend les clones complets volumineux  
331- Utilisez un clone superficiel si vous travaillez uniquement sur le contenu : `git clone --depth 1`  
332- Excluez les traductions des recherches quand vous travaillez sur le contenu anglais  
333- Les processus de build peuvent être lents lors de la première exécution (npm install, build Vite)  
334 
335## Considérations de sécurité
336 
337### Variables d’environnement
338 
339- Les clés API ne doivent jamais être commises dans le référentiel  
340- Utilisez des fichiers `.env` (déjà dans `.gitignore`)  
341- Documentez les variables d’environnement requises dans les README projets  
342 
343### Projets Python
344 
345- Utilisez des environnements virtuels : `python -m venv venv`  
346- Gardez les dépendances à jour  
347- Les tokens GitHub doivent avoir les permissions minimales nécessaires  
348 
349### Accès aux modèles GitHub
350 
351- Tokens d’accès personnel (PAT) requis pour les modèles GitHub  
352- Les tokens doivent être stockés en variables d’environnement  
353- Ne jamais commettre de tokens ou d’identifiants  
354 
355## Notes supplémentaires
356 
357### Public cible
358 
359- Débutants complets au développement web  
360- Étudiants et autodidactes  
361- Enseignants utilisant le programme en classe  
362- Contenu conçu pour l’accessibilité et le développement progressif des compétences  
363 
364### Philosophie éducative
365 
366- Approche par projets  
367- Vérifications fréquentes des connaissances (quiz)  
368- Exercices pratiques de programmation  
369- Exemples d’applications réelles  
370- Focus sur les fondamentaux avant les frameworks  
371 
372### Maintenance du référentiel
373 
374- Communauté active d’apprenants et contributeurs  
375- Mises à jour régulières des dépendances et du contenu  
376- Surveillance des issues et discussions par les mainteneurs  
377- Mises à jour de traductions automatisées via GitHub Actions  
378 
379### Ressources associées
380 
381- [Modules Microsoft Learn](https://docs.microsoft.com/learn/)  
382- [Ressources du Student Hub](https://docs.microsoft.com/learn/student-hub/)  
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) recommandé pour les apprenants  
384- Cours additionnels : IA générative, Data Science, ML, IoT disponibles  
385 
386### Travailler avec des projets spécifiques
387 
388Pour des instructions détaillées sur les projets individuels, consultez les fichiers README dans :  
389- `quiz-app/README.md` - application quiz Vue 3  
390- `7-bank-project/README.md` - application bancaire avec authentification  
391- `5-browser-extension/README.md` - développement d’extension navigateur  
392- `6-space-game/README.md` - développement de jeu Canvas  
393- `9-chat-project/README.md` - projet assistant chat IA  
394 
395### Structure Monorepo
396 
397Bien que ce ne soit pas un monorepo traditionnel, ce référentiel contient plusieurs projets indépendants :  
398- Chaque leçon est autonome  
399- Les projets ne partagent pas de dépendances  
400- Travaillez sur des projets individuels sans impacter les autres  
401- Clonez le référentiel complet pour l’expérience complète du programme
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Avertissement** :  
407Ce document a été traduit à l’aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforcions d’assurer l’exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue d’origine doit être considéré comme la source faisant autorité. Pour les informations critiques, une traduction professionnelle humaine est recommandée. Nous déclinons toute responsabilité en cas de malentendus ou d’interprétations erronées résultant de l’utilisation de cette traduction.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->