229 lines
6.8 KiB
Markdown
229 lines
6.8 KiB
Markdown
# 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 ! 🙏
|
|
|