lionsdev/primefaces-freya-extension
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
primefaces-freya-extension/CONTRIBUTING.md

6.8 KiB
Raw Permalink Blame History

Guide de Contribution

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

📋 Table des matières

🤝 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
  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

    git clone https://github.com/lions-dev/primefaces-freya-extension.git
cd primefaces-freya-extension

  2. Compiler le projet

    mvn clean install

  3. Lancer la démo en mode dev

    cd integration-tests
mvn quarkus:dev

  4. Accéder à la démo

Créer un nouveau composant

  1. Créer le fichier composite dans runtime/src/main/resources/META-INF/resources/freya/

    Exemple : fieldExample.xhtml

    <?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

    <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 
    git checkout -b feat/mon-nouveau-composant
  3. Faire vos modifications
  4. Tester localement 
    mvn clean install
cd integration-tests
mvn quarkus:dev
  5. Commit vos changements 
    git commit -m "feat(fieldExample): ajout du nouveau composant"
  6. Push vers votre fork 
    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 :

Merci de contribuer ! 🙏