Contribution à iText 7 Community

Nous aimerions que vous contribuiez à notre code source et qu'iText 7 Community soit encore meilleure ! Voici les directives que nous aimerions vous voir suivre :

Contribution à iText 7 Community

Vous avez une question ou un problème ?

Si vous avez des questions sur l'utilisation d'iText 7 Community, veuillez les adresser à Stack Overflow.

Si vous êtes un client avec un contrat de support,vous avez également un accès direct à notre JIRA et à nos développeurs.

Vous avez rencontré un problème ?

Si vous trouvez un bug dans le code source ou une erreur dans la documentation, vous pouvez nous aider en soumettant une demande de tirage avec un correctif.

Veuillez consulter les Directives de soumission ci-dessous.

Vous souhaitez implémenter une fonctionnalité ?

Si vous souhaitez implémenter une nouvelle fonctionnalité, prenez en compte le type de modification :

  • Les changements majeurs que vous souhaitez apporter au projet doivent être discutés d'abord afin que nous puissions mieux coordonner nos efforts, éviter les doublons et vous aider à élaborer le changement pour qu'il soit accepté dans le projet. Contactez-nous à l'adresse community@itextpdf.com.

  • Les petites modifications peuvent être créées et soumises au référentiel GitHub en tant que demande de tirage.

Directives de soumission

Soumission d'une question ou d'un problème

Avant de soumettre votre question ou problème, faites des recherches dans Stack Overflowvotre question a peut-être déjà reçu une réponse.

Si votre problème semble être un bug et n'a pas été signalé, posez une question sur Stack Overflow pour vérifier que c'est effectivement un bug et non une erreur dans votre propre code. Aidez-nous à optimiser les efforts que nous pouvons déployer pour résoudre les problèmes et ajouter de nouvelles fonctionnalités, en évitant de signaler les problèmes en double. Fournir les informations suivantes augmentera vos chances de voir votre problème traité rapidement :

  • Comment poser de bonnes questions

  • Vue d'ensemble du problème - en cas d'erreur, une trace de pile non réduite aide

  • Motivation ou Cas d'utilisation - expliquez pourquoi cela représente un bug pour vous

  • Version(s) iText - est-ce une régression ?

  • Système d'exploitation - est-ce un problème sur Windows ou Linux, peut-être sur Mac ?

  • Reproduire l'erreur - fournir un exemple court, autonome, correct (compilable),également appelé exemple minimal, complet et vérifiable.

  • Problèmes connexes - un problème similaire a-t-il déjà été signalé ?

  • Suggérer un correctif - si vous ne pouvez pas corriger le bug vous-même, vous pouvez peut-être nous orienter vers ce qui pourrait être la cause du problème (ligne de code ou validation)

  • Marquer la question - ajoutez le tag itext7 à votre question afin que nous puissions le trouver.

Si vous obtenez de l'aide, aidez les autres. Rien de tel qu'un bon karma !

Soumission d'une demande de tirage

Avant de soumettre votre demande de tirage, tenez compte des directives suivantes :

  • Recherchez dans GitHub une demande de tirage ouverte ou fermée qui concerne votre soumission. Ne perdez pas de temps pour rien.

  • Vérifiez que la modification que vous proposez n'a pas déjà été traitée dans la branche de développement.

  • N'envoyez pas de demande de tirage distincte pour chaque fichier que vous modifiez.

  • Veuillez signer l'Accord de licence contributeur iText (iCLA) avant d'envoyer des demandes de tirage pour tout changement de plus de 20 lignes significatives de code (nous ne comptons pas les accolades et autres sucres syntaxiques). Nous ne pouvons pas accepter de code sans cet accord.

  • Clonez iText 7 Community sur votre machine locale.

    git clone git@github.com:itext/itext7.git
    cd itext7
    git fetch origin
    git checkout -b develop origin/develop
    
  • Effectuez vos modifications dans une nouvelle branche git hors de la branche de développement :

    git checkout -b my-fix-branch develop
    
  • Créez votre correctif, y compris les cas types appropriés.

  • Suivez nos Règles de codage.

  • Exécutez la suite de tests complète d'iText 7 Community et assurez-vous que tous les tests sont réussis.

  • Validez vos modifications à l'aide d'un message de validation descriptif qui suit nos conventions de message de validation.

    git commit -a
    

    Remarque : l'option de ligne de commande de validation optionnelle -a ajoutera automatiquement les fichiers modifiésadd et rm.

  • Il s'agit du moment idéal pour corriger vos validations (le cas échéant) avec git rebase --interactive.

  • Concevez vos modifications localement pour vous assurer que tous les tests réussissent.

  • Poussez votre branche vers votre compte GitHub :

    git remote add my-remote git@github.com:my-remote/itext7.git
    git push my-remote my-fix-branch
    
  • Dans GitHub, envoyez une demande de tirage à itext7: develop.

  • Si nous suggérons des modifications :

    • Effectuez les mises à jour requises.

    • Relancez la suite de tests iText 7 Community pour vous assurer que les tests sont toujours en cours.

    • Redéfinissez votre branche et poussez vers votre référentiel GitHub (votre demande de tirage sera ainsi mise à jour) :

      git fetch origin
      git rebase develop -i
      git push my-remote my-fix-branch -f
      

      Et voilà ! Nous vous remercions de votre contribution !

Après la fusion de votre demande de tirage

Une fois votre demande de tirage fusionnée, vous pouvez supprimer votre branche en toute sécurité et effectuer les modifications à partir du référentiel principal (en amont) :

  • Supprimez la branche distante sur GitHub via l'interface utilisateur Web GitHub ou votre shell local comme suit :

    git push my-remote --delete my-fix-branch
    
  • Découvrez la branche de développement :

    git checkout develop -f
    
  • Supprimez la branche locale :

    git branch -D my-fix-branch
    
  • Mettez à jour votre développement avec la dernière version en amont :

    git pull --ff upstream develop
    

Règles de codage

Pour assurer la cohérence du code source, gardez ces règles à l'esprit lorsque vous travaillez :

  • Nous développons dans Java d'abord, puis exportons vers .NET ; nous préférons donc les soumissions de code en Java. Néanmoins, cela ne devrait pas vous empêcher de faire une demande de tirage au port .NET.

  • Tout le code Java doit être Java 7. Désolé, pas d'expressions lambda ou d'autres fonctionnalités de langage Java 8.

  • Toutes les fonctionnalités ou correctifs doivent être testés par un ou plusieurs tests unitaires.

  • Toutes les méthodes API publiques doivent être documentées avec JavaDoc. Pour voir comment nous documentons nos API, veuillez consulter les javadocs existants.

  • Nous suivons les règles contenues dans les conventions de code d'Oracle pour le langage de programmation Java,avec ces ajouts :

    • Enveloppez tout le code à 100 caractères.

Directives de validation Git

Nous avons des directives sur le formatage de nos messages de validation git. Cela permet d'obtenir plus de messages lisibles faciles à suivre en cas de recherche dans l'historique du projet. Nous utilisons également les messages de validation git pour générer le journal des modifications iText 7 Community.

Ces directives sont extraites du blog de Chris Beams How to Write a Git Commit Message (Comment rédiger un message de validation git).

Format du message de validation

Chaque message de validation consiste en un objet, un corps et un pied de page :

<subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Aucune ligne du message de validation ne doit contenir plus de 72 caractères ! Cela facilite la lecture du message sur GitHub, ainsi que dans divers outils git.

Objet

L'objet contient une description succincte de la modification :

Corps

Pied de page

Le pied de page contient des informations au sujet des modifications majeures et est également l'endroit qui fait référence aux problèmes JIRA ou GitHub que cette validation résout.

Signature de l'iCLA

Veuillez signer l'Accord de licence contributeur iText (iCLA) avant d'envoyer des demandes de tirage. Pour toute modification de code plus importante (plus de 20 lignes de code significatif) à accepter, l'iCLA doit être signé. Le processus est rapide, promis !

Vous devrez (digitally) signer, puis envoyer par e-mail, fax ou voie postale le formulaire.

Code de conduite du contributeur

Veuillez noter que ce projet est publié avec un Code de conduite de contributeur. En participant à ce projet, vous acceptez de respecter ses conditions.

Nous utilisons le réseau Stack Exchange pour un support gratuit et GitHub pour l'hébergement de code. En utilisant ces services, vous acceptez de respecter leurs conditions :