wiki:fr/patchs
developer.jelix.org is not used any more and exists only for history. Post new tickets on the Github account.
developer.jelix.org n'est plus utilisée, et existe uniquement pour son historique. Postez les nouveaux tickets sur le compte github.

Version 19 (modified by laurentj, 9 years ago) (diff)

--

Proposer un patch

Pour proposer une modification, vous devez suivre les mêmes étapes que celles du développement de Jelix, expliquée ici :

  1. récupération de la dernière version de jelix dans le dépôt mercurial et non pas les fichiers disponibles en téléchargement
  2. création d'un fichier de paramètres pour le générateur
  3. modification des fichiers sources de jelix (correction de bug, amélioration, nouvelle fonctionnalité etc..)
  4. lancement du générateur de sources finales. On obtient un "build"
  5. test du build avec une application
  6. si le test est ok, on fait un patch, sinon on recommence à l'étape 2.

Vous avez vu toutes les étapes 1 à 5 précédemment. Maintenant voyons pour le patch.

ce que doit contenir votre patch

Votre patch contient bien sûr les modifications dans le code, mais pas seulement. Il doit aussi contenir les modifications des en-têtes (nom, copyright etc..), et les modifications des fichiers de build (ceux situés dans build/manifests/) si votre patch concerne l'ajout d'une fonctionnalité tel un plugin template ou un contrôle jForms etc... . Bien lire attentivement les conventions de codage.

création du patch

Vous créez un patch occasionnellement

Dans le répertoire des sources issues du dépôt mercurial, vous avez donc normalement effectué vos modifications. Placez vous alors dans le répertoire trunk (ou celui d'une branche si c'est une modification sur une branche), et tapez ensuite la commande

hg diff > monpatch.diff

Vous obtenez un fichier monpatch.diff, que vous proposerez ensuite dans un ticket.

Il se peut que vous ayez à faire la même modification dans plusieurs branches (par exemple dans trunk/ et aussi dans branches/1.0.x, pour corriger un bug existant dans les deux branches). Cependant il peut y avoir des différences importantes sur les fichiers concernées entre les deux branches, d'une fait d'évolutions dans l'une et pas dans l'autre. Aussi faire un patch pour l'une n'est pas forcément valable dans l'autre. C'est pourquoi il ne suffit souvent pas de recopier les fichiers d'une branche à une autre, mais bien de faire des modifications différentes.

Aussi dans un premier temps, il faut vérifier que les fichiers concernés sont "à peu prés" pareil. Pour cela, vous pouvez aller dans la branche où il faut appliquer les modifications de l'autre branche, en faisant :

cd repertoire/de/branche && hg import --no-commit monpatch.diff

Si il n'y a pas de conflits détectés, vérifiez les modifications faites, vérifiez que tout fonctionne bien, lancer les tests unitaires, et si c'est ok, vous pouvez créer le diff qui correspond à cette branche (hg diff)

Si il y a des conflits, des fichiers manquants etc, il va falloir appliquer les modifications à la main, faire des tests etc.. Il est possible d'utiliser hg clone pour recopier des nouveaux fichiers d'une branche à une autre, ou faire un hg merge.

Vous êtes un contributeur actif

Si vous fournissez des patches régulièrement (indépendants ou non), la meilleure façon est de gérer une pile de patches, avec l'extension mercurial "mq". Pour cela il n'est pas recommandé d'avoir sa propre branche ou fork du repository, car un reviewer peut refuser le commit. Vous aurez alors plusieurs commits pour un simple patch, et le problème est que nous voulons un historique "clair" (un commit par ticket, excepté pour les grosses modifications).

Lisez la page dédiée pour en savoir plus sur l'utilisation de mq pour contribuer à jelix.

Vous souhaitez proposer quelques patches pour une grosse modification

Maintenir une queue de patch peut être fatiguant quand vous travaillez sur une grosse modification (intégrer un nouveau composant par exemple, qui demande beaucoup de travail, donc de commits). La meilleure façon, dans ce cas, est d'avoir sa propre branche, avec ses propres commits, et cette branche sera mergée dans le trunk à la fin.

Bitbucket vous permet de publier un clone d'un dépôt, et d'y commiter les modifications. Ensuite vous pouvez utiliser la fonction "pull request" de bitbucket pour informer le propriétaire du dépôt officiel, d'intégrer votre commit dans son dépôt.

Donc vous pouvez "forker" le dépôt jelix, commiter dans votre clone et demander un pull. Ajouter un commentaire dans le ticket correspondant sur developer.jelix.org pour informer les autres contributeurs que vous avez fait des modifications.

Afin d'obtenir un historique compréhensible, essayer de faire des commits clairs. Chaque changement devrait correspondre à une étape spécifique de modifications. N'hésitez pas à utiliser l'extension Mercurial mq pour tracer vos modifications avant de les commiter dans votre clone sur bitbucket. Et bien sûr vos messages de changement doivent être bien formatés?.

Proposer le patch

Enregistrez votre fichier patch, soit dans un ticket existant concernant la modification que vous avez effectué, soit dans un nouveau ticket. Vous enregistrez le patch en cliquant sur le bouton "attach file" dans le ticket.

Si vous avez utilisé une pile de patch (mq) stockée sur bitbucket, vous pouvez indiquer simplement l'URL de votre dépôt de pile de patchs ainsi que le nom du patch.

Il se peut que ce soit un patch incomplet (vous n'avez pas le temps de le finir, vous voulez passer la main, ou alors ce n'est qu'une première étape etc...), dans ce cas là, vous vous arrêtez là. (Toutefois un commentaire ne sera pas de trop pour indiquer le pourquoi, où vous en êtes etc..)

Sinon, si votre patch vous semble prêt, sélectionnez "review?" dans le champs review du ticket. Cela veut dire que vous demandez une review.

Un "reviewer" regardera alors votre patch, et vous dira en retour si il y a des améliorations à faire (il mettra "review-") ou si c'est bon ("review+").

Si il y a "review-", il faudra faire les améliorations demandées et proposer un nouveau patch que vous attacherez sur le même ticket. Et vous demanderez alors une nouvelle review ("review?"). Et ainsi de suite.

Une fois que vous avez "review+", si vous avez les droits pour commiter dans le dépôt mercurial, vous incluez alors vos modifications dans le dépôt. Sinon un "commiter" le fera à votre place. Voir les conventions pour commiter?.


Sommaire