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 16 (modified by laurentj, 10 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 && patch -p0 < 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 queue 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. Donc vous avez plusieurs commits pour une simple patch, et le problème est que nous voulons un historique "clair" (un commit par ticket, excepté pour les grosses modifications).

Vous pouvez héberger votre queue seulement sur votre ordinateur, ou vous pouvez partager votre queue sur bitbucket. Si vous n'utilisez pas bitbucket, attachez juste vos patches aux tickets correspondant et proposer le patch (voir plus bas)

Si vous souhaitez partager votre queue de patch ( et il peut être utilite au reviewer de voir l'historique des modification dans votre patch, review après review) vous pouvez utiliser bitbucket. Créer vous un compte sur bitbucket.org, et suivez les instructions (remplacez "jelix-trunk" par jelix-1.1.x ou autre nom de branche si vous souhaitez travailler avec des branches):

  • Allez sur on http://bitbucket.org/jelix/jelix-trunk/
  • cliquez sur "patch queue", remplissez le formulaire, en donnant un nom à votre dépôt pour la queue. Prenez par exemple "jelix-trunk-patches"
  • vous pouvez alors clonez votre nouveau dépôt qui contient le patch (utilisez qclone, et non clone !):
    hg qclone ssh://hg@bitbucket.org/your-login/jelix-trunk-patches
    
  • Sur votre ordinateur, vous avez à présent un répertoire jelix-trunk-patches, avec un répertoire .hg/patches/ . Maintenant remplissez le répertoire avec le contenu de jelix-trunk, pour avoir les sources du code de jelix avec votre queue de patch
    cd jelix-trunk-patches
    hg pull -u ssh://hg@bitbucket.org/jelix/jelix-trunk
    

Vous pouvez commencer à travailler. Créons notre premier patch:

# créer le patch
hg qnew ticket123.patch

# faites quelques modifications
...
# rafraichissez le patch à chaque fois que vous faites une modification
hg qrefresh

# vous pouvez commiter la modification '''dans la queue du patch''', non dans le dépôt lui-même
hg qcommit -m "mon premier travail sur le patch du ticket 123"

Vous pouvez répéter qrefresh, qcommit pour améliorer votre patch.

Il est conseillé également d'inclure directement dans le patch le message qui sera indiqué dans le commit lorsque le patch sera intégré définitivement dans le dépôt officiel. Cela facilitera le travail de celui qui fera cette intégration, si vous n'avez pas les droits sur le dépôt officiel. Pour cela utilisez l'option -m de qrefresh:

hg qrefresh -m "ticket #123: bug fix on bla bla bla" -u "votre nom ou login bitbucket"

Les messages de commit doivent respecter un format?. Cela inclus également votre nom. Si vous ne voulez pas avoir à indiquer le nom à chaque fois, mettez le dans la configuration mercurial (fichier hgrc).

Vous pouvez créer plusieurs patch avec qnew. Souvenez vous que les modifications que vous faites sont pour le dernier patch. Si vous voulez faire un changement dans un ancien patch, vous devez utiliser qpop pour supprimer les patchs du haut. Pour appliquer à nouveau le patch le plus récent, utilisez qpush.

Lisez the tutorial on queues pour en connaitre d'avantage sur les queues.

Chaque fois que vous voulez mettre à jour les source de jelix, faites

hg qpop -a  # supprimer vos patches (de la file d'attente des patches) du code source
hg pull -u ssh://hg@bitbucket.org/jelix/jelix-trunk
hg qpush -a # ajouter les patches (de la file d'attente des patches) au code source

Si des conflits sont détectés pendant hg qpush, corriger les conflits (n'oubliez pas de faire hg qrefresh) et recommencez qpush jusqu'à ce que ce soit ok.

Pour publier vos patches sur bitbucket, allez dans le répertoire .hg/patches et tapez :

hg push

Quand un de vos patchs est prêt, allez dans le ticket correspondant sur developer.jelix.org et demandez une review, en indiquant l'URL de votre du dépôt de votre queue sur bitbucket et le nom du patch. Voir ci dessous pour proposer un patch

Quand votre patch est intégré au dépôt officiel, supprimer le de votre queue avant la mise à jour des sur du code de jelix.

hg qpop -a
hg qdelete ticket123.patch
hg qcommit -m "remove ticket123.patch"
cd .hg/patches/
hg push
cd ../..
hg pull -u ssh://hg@bitbucket.org/jelix/jelix-trunk
hg qpush -a

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.

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