Guide du Contributeur# 🤝 Guide du Contributeur¶
Bienvenue et merci de contribuer au projet AREA !Bienvenue et merci de contribuer au projet AREA !
Ce document décrit les conventions, le workflow git recommandé, la façon d'ouvrir des issues et des PR, et les bonnes pratiques de développement.Ce document décrit les conventions, le workflow git recommandé, la façon d'ouvrir des issues et des PR, et les bonnes pratiques de développement.
Avant de commencer---¶
-
Lisez la documentation : Parcourez ce site MkDocs et le README.md## 📋 Avant de commencer
-
Vérifiez les issues : Évitez les doublons en cherchant les issues existantes
-
Fork le repo : Si vous n'avez pas d'accès direct, travaillez sur votre fork1. Lisez la documentation : Parcourez ce site MkDocs et le README.md
-
Configurez votre environnement : Suivez le guide d'installation2. Vérifiez les issues : Évitez les doublons en cherchant les issues existantes
-
Fork le repo : Si vous n'avez pas d'accès direct, travaillez sur votre fork
Configuration de l'environnement4. Configurez votre environnement : Suivez le guide d'installation¶
Prérequis---¶
-
Node.js 18+## 🔧 Configuration de l'environnement
-
Docker & Docker Compose
-
Git### Prérequis
-
Un éditeur (VS Code recommandé)
-
Node.js 18+
Installation- Docker & Docker Compose¶
- Git
```bash- Un éditeur (VS Code recommandé)
Cloner le repository¶
git clone https://github.com/JonthanUTF/mirror_area.git### Installation
cd mirror_area
# Backend# Cloner le repository
cd servergit clone https://github.com/JonthanUTF/mirror_area.git
npm installcd mirror_area
cp .env.example .env
# Configurer les variables d'environnement# Backend
cd server
# Frontend Webnpm install
cd ../front-webcp .env.example .env
npm install# Configurer les variables d'environnement
# Application Mobile# Frontend Web
cd ../client-mobilecd ../front-web
npm installnpm install
Application Mobile¶
Lancer le projetcd ../client-mobile¶
npm install
bash
Avec Docker (recommandé)¶
docker-compose up -d### Lancer le projet
Sans Docker```bash¶
Terminal 1 - Backend# Avec Docker (recommandé)¶
cd server && npm run devdocker-compose up -d
Terminal 2 - Frontend# Ou en local¶
cd front-web && npm run dev# Terminal 1 - Backend
```cd server && npm run dev
Workflow Git# Terminal 2 - Frontend¶
cd front-web && npm run dev
Branches¶
Terminal 3 - Mobile (optionnel)¶
| Branche | Usage |cd client-mobile && npx expo start
|---------|-------|```
| main | Production stable |
| dev | Développement actif |---
| feature/* | Nouvelles fonctionnalités |
| fix/* | Corrections de bugs |## 📝 Conventions de Commit
| docs/* | Documentation |
Nous utilisons Conventional Commits pour un historique clair.
Créer une branche¶
Format¶
# Mettre à jour dev```
git checkout dev<type>(<scope>): <description>
git pull origin dev
[corps optionnel]
# Créer une branche feature
git checkout -b feature/ma-fonctionnalite[footer optionnel]
``````
### Commits### Types
Utilisez des messages de commit clairs et descriptifs :| Type | Description |
|------|-------------|
```| `feat` | Nouvelle fonctionnalité |
type(scope): description courte| `fix` | Correction de bug |
| `docs` | Documentation uniquement |
Corps optionnel avec plus de détails.| `style` | Formatage (pas de changement de code) |
```| `refactor` | Refactoring (pas de nouvelle feature ni fix) |
| `test` | Ajout ou modification de tests |
Types de commits :| `chore` | Maintenance (build, CI, dépendances) |
| Type | Description |### Scopes recommandés
|------|-------------|
| feat | Nouvelle fonctionnalité |- `backend` / `server` - API et serveur
| fix | Correction de bug |- `frontend` / `web` - Client web React
| docs | Documentation |- `mobile` - Application mobile
| style | Formatage (pas de changement de code) |- `services` - Services d'intégration
| refactor | Refactoring |- `auth` - Authentification
| test | Ajout de tests |- `docs` - Documentation
| chore | Maintenance |
### Exemples
Exemples :
```bash
```feat(services): ajouter le service Spotify
feat(services): add Dropbox service integration
fix(auth): resolve JWT expiration issuefix(auth): corriger la validation du token JWT
docs(api): update API reference for areas endpoint
```docs(api): documenter les endpoints utilisateur
### Pull Requestrefactor(backend): simplifier le moteur d'automation
1. Poussez votre branche :chore(deps): mettre à jour React vers 18.3
```bash```
git push origin feature/ma-fonctionnalite
```---
2. Ouvrez une PR vers `dev`## 🌿 Workflow Git
3. Remplissez le template de PR :### Branches
- Description des changements
- Screenshots si UI modifiée| Branche | Usage |
- Checklist de tests|---------|-------|
| `main` | Production stable |
4. Attendez la review| `develop` | Développement en cours |
| `feature/*` | Nouvelles fonctionnalités |
## Standards de code| `fix/*` | Corrections de bugs |
| `doc` | Documentation |
### JavaScript/TypeScript
### Workflow
- Utilisez ESLint et Prettier
- Évitez les `any` en TypeScript1. **Créer une branche** depuis `develop`
- Documentez les fonctions complexes ```bash
git checkout develop
```javascript git pull origin develop
/** git checkout -b feature/mon-feature
* Vérifie si un utilisateur est authentifié ```
* @param {Request} req - Requête Express
* @returns {boolean} - True si authentifié2. **Développer** avec des commits atomiques
*/
function isAuthenticated(req) {3. **Push** et créer une Pull Request
return !!req.user; ```bash
} git push origin feature/mon-feature
``` ```
### React4. **Review** par un autre contributeur
- Composants fonctionnels avec hooks5. **Merge** dans `develop` après approbation
- Props typées (TypeScript) ou PropTypes
- Un composant par fichier---
```jsx## 📮 Pull Requests
function MyComponent({ title, onClick }) {
return (### Checklist PR
<button onClick={onClick}>
{title}- [ ] Le code compile sans erreur
</button>- [ ] Les tests passent
);- [ ] La documentation est mise à jour si nécessaire
}- [ ] Le code suit les conventions du projet
```- [ ] Les commits suivent Conventional Commits
### CSS### Template PR
- Utilisez des classes descriptives```markdown
- Évitez les styles inline## Description
- Préférez les variables CSS
Brève description des changements.
```css
.area-card {## Type de changement
background: var(--bg-primary);
border-radius: var(--radius-md);- [ ] Bug fix
padding: var(--spacing-md);- [ ] Nouvelle fonctionnalité
}- [ ] Breaking change
```- [ ] Documentation
## Tests## Tests
### Lancer les testsDécrivez les tests effectués.
```bash## Screenshots (si applicable)
# Backend
cd serverAjoutez des captures d'écran.
npm test```
# Frontend---
cd front-web
npm test## 🐛 Signaler un Bug
Avant de créer une issue¶
Écrire des tests¶
- Vérifiez que le bug n'est pas déjà signalé
```javascript2. Testez avec la dernière version
describe('Area API', () => {3. Isolez le problème (reproduire le bug)
it('should create a new area', async () => {
const response = await request(app)### Template Issue Bug
.post('/areas')
.set('Authorization', `Bearer ${token}`)```markdown
.send({**Description**
name: 'Test Area',Description claire du bug.
actionService: 'timer',
actionType: 'interval',**Étapes pour reproduire**
reactionService: 'console',1. Aller sur '...'
reactionType: 'log_message',2. Cliquer sur '...'
parameters: { interval: 60000 }3. Voir l'erreur
});
**Comportement attendu**
expect(response.status).toBe(201);Ce qui devrait se passer.
expect(response.body.name).toBe('Test Area');
});Screenshots
});Si applicable.
**Environnement**
## Ajouter un nouveau service- OS: [e.g. Ubuntu 22.04]
- Navigateur: [e.g. Chrome 120]
1. Créer le fichier dans `server/src/services/implementations/`- Version Node: [e.g. 18.19.0]
const ServiceBase = require('../ServiceBase');---
class MonService extends ServiceBase {## 💡 Proposer une Fonctionnalité
constructor() {
super('monservice', 'Mon Service', 'icon-url');### Template Feature Request
this.registerAction('mon_action', 'Description', {```markdown
param1: 'string'**Problème**
});Quel problème cette fonctionnalité résout-elle ?
this.registerReaction('ma_reaction', 'Description', {**Solution proposée**
param2: 'number'Description de la solution.
});
}**Alternatives considérées**
Autres approches envisagées.
async checkTrigger(action, area, params) {
// Implémentation**Contexte supplémentaire**
return false;Informations additionnelles.
}```
async executeReaction(reaction, area, params) {---
// Implémentation
}## 🧪 Tests
}
### Lancer les tests
module.exports = new MonService();
``````bash
# Backend
2. Le service sera automatiquement chargé par le loadercd server
npm test
3. Si OAuth nécessaire, ajouter la configuration dans `routes/services.js`
# Frontend (si configuré)
4. Documenter le service dans `docs/services/`cd front-web
npm test
## Issues```
### Ouvrir une issue### Écrire des tests
Utilisez les templates fournis :- Chaque nouvelle fonctionnalité doit avoir des tests
- Les corrections de bugs doivent inclure un test de régression
- Bug report : Pour signaler un bug- Visez une couverture de code > 80%
- Feature request : Pour proposer une fonctionnalité
- Documentation : Pour des améliorations de docs---
### Labels## 📁 Structure du Code
| Label | Description |### Backend (server/)
|-------|-------------|
| bug | Quelque chose ne fonctionne pas |```
| enhancement | Nouvelle fonctionnalité |server/src/
| documentation | Documentation |├── routes/ # Endpoints API
| good first issue | Bon pour débuter |├── models/ # Modèles Sequelize
| help wanted | Aide bienvenue |├── services/ # Logique métier et intégrations
│ └── implementations/ # Services AREA
## Questions└── config/ # Configuration
Si vous avez des questions :
Frontend (front-web/)¶
-
Consultez d'abord la documentation
-
Cherchez dans les issues existantes```
-
Ouvrez une nouvelle issue avec le label "question"front-web/src/
├── pages/ # Pages/routes ├── components/ # Composants réutilisables └── assets/ # Images, styles
client-mobile/src/ ├── screens/ # Écrans ├── components/ # Composants ├── navigation/ # Configuration navigation └── api/ # Client API---
## 🎨 Style de Code
### JavaScript/TypeScript
- Indentation : 2 espaces
- Quotes : simples `'`
- Point-virgule : oui
- Nommage : camelCase pour variables/fonctions, PascalCase pour classes/composants
### Outils recommandés
- **ESLint** : Linting
- **Prettier** : Formatage
- **EditorConfig** : Cohérence éditeur
---
## 📞 Contact
- **Issues GitHub** : Pour bugs et features
- **Pull Requests** : Pour contributions
- **Email** : Voir le profil du repo
---
Merci de contribuer à AREA ! 🚀
- chore – tâches de maintenance (build, deps)
- refactor – refactor sans ajout de fonctionnalité
- test – ajout/modification de tests
---
## 3️⃣ Branches & workflow
Modèle proposé (adaptable selon règles du cours / orga) :
- `main` : code stable (production). Ne pas pousser directement.
- `dev` : intégration continue des fonctionnalités validées.
- `feature/<desc>` : branche pour chaque nouvelle fonctionnalité.
- `fix/<desc>` : branche pour correctifs.
Règles :
- Crée les branches depuis `dev`.
- Ouvre une PR de `feature/*` ou `fix/*` vers `dev`.
- `dev` est mergeable vers `main` via PR après validation (tests + revue).
- Protections recommandées : protection de `main` et `dev`, checks obligatoires, revue obligatoire.
Remarques pratiques :
- Rebase régulièrement sur `dev` pour limiter les conflits.
- Nomme les branches claires et courtes (`feature/login-oauth`).
---
## 4️⃣ Issues
- Toujours créer une issue pour un bug ou une nouvelle feature.
- Utilise les templates fournis (bug/feature/documentation/enhancement) si présents.
Contenu minimal d'une bonne issue :
- Titre explicite
- Contexte et version
- Étapes pour reproduire (pour les bugs)
- Comportement attendu vs observé
- Logs / captures / exemples
- Tags/label suggérés
Quand soumettre :
- Pour une feature : explique la valeur ajoutée, les critères d'acceptation et les dépendances.
- Pour un bug : fournis un cas reproductible et, si possible, une PR de correctif.
---
## 5️⃣ Pull Requests (PR)
PR → doit cibler `dev` (sauf règle contraire).
Chaque PR doit contenir :
- Titre clair (ex: `feat(api): support OAuth callback`)
- Description : ce qui change, pourquoi, impact, screenshots si nécessaire
- Issues liées : `Closes #<num>` pour fermer automatiquement une issue
- Checklist : tests, build, doc
Template de PR recommandé :
Description: - Qu'est-ce qui a été changé ? - Pourquoi ?
Issues liées:
- Closes #
Checklist: - [ ] Code formaté et lint passé - [ ] Tests unitaires ajoutés / mis à jour (si applicable) - [ ] Documentation mise à jour (si applicable)
Bonnes pratiques :
- Faire des PR petites et ciblées.
- Décrire clairement l'impact et tout risque potentiel.
- Demander au moins une revue — ajouter des reviewers pertinents.
---
## 6️⃣ Revue de code
Critères de revue :
- Lisibilité et architecture
- Tests ajoutés/maintenus
- Respect des règles de sécurité et absence de secrets
- Pas de régressions connues
Comportement attendu des reviewers :
- Être constructif et concret
- Proposer des alternatives/clés d'amélioration
- Valider les tests et checks CI
---
## 7️⃣ Tests & CI
- Ajoute/maintiens des tests pour les changements importants.
- Assure-toi que la CI (GitHub Actions etc.) passe avant de demander le merge.
- Les checks peuvent inclure lint, build, tests unitaires et déploiement de preview.
---
## 8️⃣ Documentation & MkDocs
- La documentation est gérée avec MkDocs (voir `mkdocs.yml`).
- Pour développer localement :
```bash
# créer et activer un venv (optionnel)
python3 -m venv .venv
source .venv/bin/activate
pip install mkdocs mkdocs-material
mkdocs serve
# ouvrir http://127.0.0.1:8000
- Pour déployer sur GitHub Pages :
mkdocs gh-deploy(ou via Actions). - Mets à jour la doc dans
docs/et ajoute une ligne dansmkdocs.ymlnav:si tu veux ordonner les pages.
9️⃣ Checklist contribution (avant PR)¶
- [ ] Le code compile et fonctionne localement
- [ ] Les tests passent
- [ ] Les messages de commit respectent Conventional Commits
- [ ] La PR contient une description et les issues liées
- [ ] La doc est mise à jour si nécessaire
🔧 Commandes utiles¶
# créer une branche
git checkout -b feature/ma-feature dev
# faire un commit
git add .
git commit -m "feat(scope): courte description"
# pousser
git push origin feature/ma-feature
Note pour projets scolaires (ex: Epitech / Area)¶
Si ce dépôt correspond à un projet de type "Area" (ou un projet d'école comme Epitech) :
- Vérifie les consignes spécifiques du cours (naming, dépôt, livrables).
- Certaines écoles demandent des branches/PR spécifiques ou un format de rendu : adapte le workflow ci-dessus si nécessaire.
Liens utiles¶
- Conventional Commits — https://www.conventionalcommits.org/
- GitHub Actions — https://docs.github.com/en/actions
- MkDocs — https://www.mkdocs.org/
Merci pour ta contribution — ouvre une PR et on te fera une revue rapidement !