# Guide de Contribution

Merci de votre intérêt pour contribuer à **PrimeFaces Freya Extension** ! 🎉

## 📋 Table des matières

- [Code de conduite](#code-de-conduite)
- [Comment contribuer](#comment-contribuer)
- [Structure du projet](#structure-du-projet)
- [Développement](#développement)
- [Standards de code](#standards-de-code)
- [Processus de Pull Request](#processus-de-pull-request)

## 🤝 Code de conduite

Ce projet adhère à un code de conduite. En participant, vous vous engagez à respecter ce code.

- Soyez respectueux et inclusif
- Acceptez les critiques constructives
- Concentrez-vous sur ce qui est le mieux pour la communauté

## 🚀 Comment contribuer

### Signaler un bug

1. Vérifiez que le bug n'a pas déjà été signalé dans les [Issues](https://github.com/lions-dev/primefaces-freya-extension/issues)
2. Créez une nouvelle issue avec le template "Bug Report"
3. Incluez :
   - Description claire du problème
   - Étapes pour reproduire
   - Comportement attendu vs comportement actuel
   - Version de Java, Quarkus, PrimeFaces
   - Extrait de code minimal

### Proposer une fonctionnalité

1. Créez une issue avec le template "Feature Request"
2. Décrivez :
   - Le problème que cela résout
   - La solution proposée
   - Des alternatives envisagées
   - Des exemples d'utilisation

### Ajouter un nouveau composant

1. Créez une issue pour discuter du composant
2. Suivez la structure des composants existants
3. Ajoutez la documentation
4. Ajoutez des exemples dans `components-demo.xhtml`

## 📁 Structure du projet

```
primefaces-freya-extension/
├── runtime/                          # Module principal
│   └── src/main/resources/
│       └── META-INF/
│           ├── freya.taglib.xml      # Déclaration des composants
│           └── resources/
│               └── freya/            # Composants composites (.xhtml)
├── integration-tests/                # Tests et démonstration
│   └── src/main/
│       ├── java/
│       │   └── dev/lions/freya/demo/ # Beans de démonstration
│       └── resources/
│           └── META-INF/resources/   # Pages de démonstration
├── README.md                         # Documentation principale
├── CONTRIBUTING.md                   # Ce fichier
└── pom.xml                          # Configuration Maven parent
```

## 💻 Développement

### Prérequis

- Java 17 ou supérieur
- Maven 3.8+
- Git
- IDE (IntelliJ IDEA, Eclipse, VS Code)

### Configuration de l'environnement

1. **Cloner le repository**
   ```bash
   git clone https://github.com/lions-dev/primefaces-freya-extension.git
   cd primefaces-freya-extension
   ```

2. **Compiler le projet**
   ```bash
   mvn clean install
   ```

3. **Lancer la démo en mode dev**
   ```bash
   cd integration-tests
   mvn quarkus:dev
   ```

4. **Accéder à la démo**
   - Ouvrir http://localhost:8080
   - La page se recharge automatiquement lors des modifications

### Créer un nouveau composant

1. **Créer le fichier composite** dans `runtime/src/main/resources/META-INF/resources/freya/`
   
   Exemple : `fieldExample.xhtml`
   ```xml
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE html>
   <html xmlns="http://www.w3.org/1999/xhtml"
         xmlns:composite="http://xmlns.jcp.org/jsf/composite"
         xmlns:h="http://xmlns.jcp.org/jsf/html"
         xmlns:p="http://primefaces.org/ui">

       <composite:interface>
           <composite:attribute name="id" required="false" type="java.lang.String" />
           <composite:attribute name="label" required="true" type="java.lang.String" />
           <composite:attribute name="value" required="true" />
           <composite:attribute name="required" required="false" type="java.lang.Boolean" default="false" />
           <!-- Autres attributs spécifiques -->
       </composite:interface>

       <composite:implementation>
           <div class="field">
               <p:outputLabel for="#{cc.clientId}:input" value="#{cc.attrs.label}">
                   <span class="p-error" rendered="#{cc.attrs.required}"> *</span>
               </p:outputLabel>
               
               <!-- Composant PrimeFaces -->
               <p:inputText id="input" value="#{cc.attrs.value}" required="#{cc.attrs.required}" />
               
               <p:message for="#{cc.clientId}:input" />
           </div>
       </composite:implementation>
   </html>
   ```

2. **Déclarer le composant** dans `runtime/src/main/resources/META-INF/freya.taglib.xml`
   ```xml
   <tag>
       <tag-name>fieldExample</tag-name>
       <source>freya/fieldExample.xhtml</source>
   </tag>
   ```

3. **Ajouter un exemple** dans `integration-tests/src/main/resources/META-INF/resources/components-demo.xhtml`

4. **Mettre à jour la documentation** dans `README.md`

## 📝 Standards de code

### XHTML (Composants composites)

- Indentation : 4 espaces
- Toujours inclure `id`, `label`, `value`, `required` comme attributs de base
- Utiliser `<div class="field">` pour les champs de formulaire
- Inclure `<p:message>` pour les messages de validation
- Ajouter l'astérisque requis : `<span class="p-error" rendered="#{cc.attrs.required}"> *</span>`

### Java (Beans)

- Suivre les conventions Java standard
- Utiliser `@Named` et `@SessionScoped` pour les beans CDI
- Implémenter `Serializable` pour les beans avec scope
- Documenter les méthodes publiques avec Javadoc

### Commits

- Messages en français ou anglais
- Format : `type(scope): description`
  - `feat`: Nouvelle fonctionnalité
  - `fix`: Correction de bug
  - `docs`: Documentation
  - `style`: Formatage
  - `refactor`: Refactoring
  - `test`: Tests
  - `chore`: Maintenance

Exemples :
```
feat(fieldInput): ajout de l'attribut maxlength
fix(actionDialog): correction du binding widgetVar
docs(README): mise à jour de la liste des composants
```

## 🔄 Processus de Pull Request

1. **Fork** le repository
2. **Créer une branche** depuis `main`
   ```bash
   git checkout -b feat/mon-nouveau-composant
   ```
3. **Faire vos modifications**
4. **Tester** localement
   ```bash
   mvn clean install
   cd integration-tests
   mvn quarkus:dev
   ```
5. **Commit** vos changements
   ```bash
   git commit -m "feat(fieldExample): ajout du nouveau composant"
   ```
6. **Push** vers votre fork
   ```bash
   git push origin feat/mon-nouveau-composant
   ```
7. **Créer une Pull Request** sur GitHub

### Checklist avant PR

- [ ] Le code compile sans erreur
- [ ] Les tests passent (si applicable)
- [ ] La documentation est à jour
- [ ] Un exemple est ajouté dans `components-demo.xhtml`
- [ ] Le composant est déclaré dans `freya.taglib.xml`
- [ ] Le commit suit les conventions

## ❓ Questions

Pour toute question :
- Ouvrir une [Discussion](https://github.com/lions-dev/primefaces-freya-extension/discussions)
- Contacter l'équipe : contact@lions.dev

Merci de contribuer ! 🙏

