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

--

Proposer un patch

Le code de Jelix est hébergé sur le site Github, qui permet d'apporter des modifications directement en ligne. N'utilisez cette fonctionnalité que pour les modifications très mineures, comme des erreurs d'orthographe, de syntax, bref, pour les modifications qui ne touchent que quelques lignes et un unique fichier. Pour les modifications plus importantes ou qui touchent plusieurs fichiers à la fois, veuillez suivre la procédure suivante.

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 git 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

Si vous n'êtes pas familiarisé avec l'utilisation de git/github, voici la solution la plus simple. Dans le répertoire des sources issues du dépôt (vous devez donc avoir installé git et fait au moins un git clone), vous avez donc normalement effectué vos modifications. Placez vous alors dans le répertoire des sources, et tapez ensuite la commande

git 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. Proposez alors un patch pour chaque branche concernée si possible.

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, choisissez "ask a review" dans le 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 ou si c'est bon. Si ce n'est pas bon, 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. Et ainsi de suite.

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

Vous êtes un contributeur actif

Si vous fournissez des patchs régulièrement (indépendants ou non), la meilleure façon est de "forker" le dépôt de jelix dans votre compte github.

Créez une branche dans votre "fork", pour chaque modifications distinctes (pour chaque ticket en gros). Cela permettra alors de fusionner les branches qui ont été acceptées sans inclure vos modifications non terminées ou refusées.

Important: Vos changements doivent s'effectuer sur les bonnes branches. Vous ne proposerez des modifications dans les branches des versions stables (jelix-1.2.x, jelix-1.3.x), que celles qui sont des corrections de bugs. Pas d'amélioration ou de fonctionnalités qui changent un comportement, qui peuvent provoquer des régressions etc. Les petites améliorations qui ne font qu'ajouter un plugin ou une méthode sont susceptibles toutefois d'être acceptés. Rappelez-vous, ce sont des branches stables. On doit pouvoir mettre à jour Jelix sans avoir à toucher à l'application (sauf si bien sûr, il y a une correction d'un trou de sécurité qui impose de le faire). Bref, toutes les nouveautés doivent être faites dans la branche master.

Pour les petites modifications, essayez de limiter le nombre de commit. La review sera plus simple et cela permettra de garder un historique clair. Pour les modifications plus conséquentes, il est préférable bien sûr d'avoir plusieurs commits, un pour chaque étape. Afin d'obtenir un historique compréhensible, essayer de faire des commits clairs. Chaque changement devrait correspondre à une étape spécifique de modifications.

Lisez la page sur les commits pour le format des messages des commits.

Quand votre modification est prête, faites un "pull request" sur github. Si il y a un ticket correspondant sur developer.jelix.org, vous pouvez aussi informer sur ce ticket vos travaux (en choisissant "ask a review" dans le ticket par exemple). Un reviewer vérifiera alors votre code, proposera peut-être des améliorations à faire, et ensuite importera vos changements dans le dépôt officiel.


Sommaire