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 10 (modified by foxmask, 10 years ago) (diff)

ajout des spécificité mercurial à traduire (non terminée)

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 reguliè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 rereview) 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 branch 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. Prennez 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:

# creer le patch
hg qnew ticket123.patch

# faites quelques modifications
...
# rafraichissez le patch à chaque vois 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 "my first work on the patch for ticket 123"

Vous pouvez répéter qrefresh, qcommit pour améliorer votre patch. Vous pouvez créer plusieurs patch avec qnew. Souvenez vous que les modifications que vous faites sont pour le dernier patch. Si vous voulez changer pour une 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 vois que vous voulez mettre à jour les source de jelix, faites

hg qpop -a  # remove your patches from the source code
hg pull -u ssh://hg@bitbucket.org/jelix/jelix-trunk
hg qpush -a

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 repertoire .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

Maintening a queue of patch can be tiring when you work on a big change (integration of a new big component for example). The best way in this case is to have your own branch, with your own commits, and this branch will be merge with the trunk at the end.

Bitbucket allow you to publish a clone of a repository, and to commit changes to it. Then you can use the feature "pull request" of bitbucket to inform the owner of the "official" repository, to integrate your commit into his repository.

So you can "fork" a jelix repository, commit into your clone, and request a pull. Add a comment on the corresponding ticket on developer.jelix.org to inform other contributors that you've made some changes.

Try to commit clear step, in order to have an understandable history. Each changeset should correspond to a specific step of the change. Don't hesitate to use the mq extension of Mercurial to track your changes before committing them into your clone on bitbucket. And of course, your messages of changset should be well formatted?.

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, selectionnez "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