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

ajout des spécificité mercurial à traduire (en cours)

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 active

If you provide often some patches (unrelated or not), the best way is to manage a queue of patch, with the "mq" extension of Mercurial. Having his own branch/fork of the repository for that is not recommended, as a reviewer can refused your commit. So you can have at the end several commit for a single "patch", and the problem is that we want to have a clear history (one commit per ticket, except for big changes).

You can host your queue only on your computer, or you can share your queue on bitbucket. If you don't use bitbucket, just attach your patches on corresponding tickets and then request a review (see below).

If you want to share your queue of patchs (and it can be useful for reviewer to see the history of changes on your patch, review after review), you can use bitbucket. Create an account on bitbucket.org, and follow this instructions (replace "jelix-trunk" by jelix-1.1.x or other branch name if you want to work with branches):

  • Go on http://bitbucket.org/jelix/jelix-trunk/
  • click on "patch queue", fill the form, by giving a name to your repository for the queue. Take "jelix-trunk-patches" for example
  • you can then clone your new repository which contains the patch (use qclone, and not clone !):
    hg qclone ssh://hg@bitbucket.org/your-login/jelix-trunk-patches
    
  • On your computer, you have now a jelix-trunk-patches directory, with a .hg/patches/ directory. Now fill the directory with the content of jelix-trunk, to have source code of jelix with your patchs queue
    cd jelix-trunk-patches
    hg pull -u ssh://hg@bitbucket.org/jelix/jelix-trunk
    

You can start now to work. Let's create a first patch:

# create the patch
hg qnew ticket123.patch

# do some modifications on files
...
# refresh the patch each time you made some modifications
hg qrefresh

# you can then commit modification '''in the patch queue''', not in the repository it self
hg qcommit -m "my first work on the patch for ticket 123"

You can repeat qrefresh, qcommit to improve your patch. You can create several patch with qnew. Remember that changes you make are for the last patch. If you want to change an older patch, you have to use qpop to remove top patchs. To apply again newer patch, use qpush.

Read the tutorial on queues to know more on queues.

Each time you want to update source code of jelix, do

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

If conflicts are detected during hg qpush, fix conflicts (don't forget to do hg qrefresh) and restart qpush until it is ok.

To publish your patches on bitbucket, go into the directory .hg/patches and:

hg push

When one of your patch is ready, go on the corresponding ticket on developer.jelix.org and ask a review, by indicating the URL of your queue repository on bitbucket and the name of the patch. See below to request a review.

When one of your patch is integrated in the official repository, delete it from your queue before updating the source code of 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