Contribuer au projet Pod

Sommaire

1. Avant de commencer le développement
2. Le modèle de développement
   1. Convention des noms de branches
   2. Basculement vers la branche de développement
   3. Branche de travail
   4. Pousser votre travail
   5. Conclure votre travail
3. Pull Request
4. Normes de développement pour les nouvelles fonctionnalités
   1. Les variables de configuration
   2. Le format de code Python
   3. La traduction

Avant de commencer le développement

La préparation à faire avant de commencer son développement.

Préparatifs

Il est nécessaire d'avoir terminé l'installation de Pod (Installation) pour mieux comprendre par la suite.

Ensuite procéder comme suit :

• A partir du depot Pod procéder à un fork sur github (Cliquez sur le bouton 'Fork' sur le coté en haut à droite de la page du dépot Pod).
• Créer un répertoire qui contiendra votre travail. Par exemple /usr/local/django_projects pour reprendre ce qui a été dit dans l'installation et faites un clone de votre projet qui vient d'être fork.
• Faites un remote pour synchroniser votre fork avec le dépot original.

$ git remote add upstream https://github.com/EsupPortail/pod/

• Vérifier avec un git remote -v. Vous devriez normalement voir les liens de votre fork (origin) et du dépot d'origine (upstream).
• Pour maintenir synchroniser votre dépot avec le dépot d'origine :

$ git fetch upstream
remote: Counting objects: 75, done.
remote: Compressing objects: 100% (53/53), done.
remote: Total 62 (delta 27), reused 44 (delta 9)
Unpacking objects: 100% (62/62), done.
From https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY
 * [new branch]      master     -> upstream/master
$ git checkout dev
$ git merge upstream/dev

Par exemple pour tenir à jour votre branche dev avec celle du dépot d'origine.

Désormais le reste de la documentation part du principe que vous travaillez sur le dépot forké.

Le modèle de développement

Comment procéder à son développement.

Convention des noms de branches

Le développement ne se fait pas directement sur la branche master du projet.
Quand vous désirez ajouter une fonctionnalité, il faudra créer votre propre branche à partir de la branche de développement (ici "dev"). Elle prendra la forme de :

loginGIT/feature-intitulé_de_la_fonctionnalité
Par exemple :
toto/feature-add_unit_test_enrich_view

Quand il s'agit d'un bugfix/hotfix il faudra créer votre propre branche à partir de la branche master. Elle prendra la forme de :

loginGIT/bugfix-intitulé_du_bugfix
loginGIT/hotfix-intitulé_du_hotfix
Par exemple :
toto/bugfix-video_template

Un hotfix correspond à la correction d'une fonctionnalité qui ne fonctionne pas du tout.
Un bugfix correspond à la correction d'une fonctionnalité qui marche mais pas comme désiré.

Basculement vers la branche de développement

(Dans le cas d'un ajout de fonctionnalité, sinon sauter cette étape)

Auparavant vous avez normalement créé un répertoire /usr/local/django_projects et cloné votre fork du dépot pod. De plus vous êtes dans votre environnement virtuel. Et je continue avec "upstream" comme nom de mon remote.

Il est nécessaire de basculer vers la branche dev de pod :

(django_pod) pod@podvm:~$ cd django_projects/pod/
(django_pod) pod@podvm:-/django_projects/pod$ git checkout --track upstream/dev

Branche de travail

Vous allez créer maintenant votre branche de travail :

(django_pod) pod@podvm:~/django_projects/pod$ git branch pseudogit/feature-nouveau_truc_bien
(django_pod) pod@podvm:~/django_projects/pod$ git checkout pseudogit/feature-nouveau_truc_bien

Cette commande peut aussi se faire grâce à :

(django_pod) pod@podvm:~/django_projects/pod$ git checkout -b pseudogit/feature-nouveau_truc_bien

Pousser votre travail

Quand vous le jugez nécessaire vous devez pousser votre travail vers votre dépot :

(django_pod) pod@podvm:~/django_projects/pod$ git push origin pseudogit/feature-nouveau_truc_bien

(Jamais de "git push origin master" !)
Dans le cas où vous auriez terminé la nouvelle fonctionnalité il faudra procéder à un pull request sur la branche "dev" du dépot d'origine à partir de github pour intégrer votre travail dans le processus de développement. Voir plus bas pour cette procédure.
Si il s'agit d'un hotfix/bugfix il faudra procéder à un pull request sur la branche "master" du dépot d'origine.

Conclure votre travail

Quand votre pull request a été accepté et votre travail intégré à la branche de développement il faut retourner à la branche de développement et la tenir à jour.

(django_pod) pod@podvm:~/django_projects/pod$ git checkout dev
(django_pod) pod@podvm:~/django_projects/pod$ git pull

Après c'est à vous de voir si vous voulez garder votre ancienne branche de travail ou non. Par soucis d'historique les branches de travail terminé sont conservés dans le dépot pod mais vous pouvez supprimer votre branche localement :

(django_pod) pod@podvm:~/django_projects/pod$ git branch -d pseudogit/feature-nouveau_truc_bien

Pull Request

Comment faire une Pull Request sur le dépôt de Pod

Les modalités d'une Pull Request

Quand vous estimez que votre nouvelle fonctionnalité ou votre correctif est terminé vous pouvez procéder à un Pull Request, c'est à dire une demande de fusion entre votre branche et celle de pod (soit dev ou master selon ce que vous apportez). Les étapes pour y arriver sont les suivantes :

1. Se rendre à "Pull requests"
2. Cliquez sur "New pull request", cela permet de proposer des merges entre les branches du dépot. Mais, dans notre cas on veut proposez des merges venant de notre dépot. Pour cela cliquez sur le lien "compare accross forks".
3. Quatre champs sont à renseigner :
   • base fork : le dépot d'origine (EsupPortail/pod)
   • base : où vous voulez fusionner (dev si c'est une feature, master si c'est un hotfix/bugfix)
   • head fork : votre dépot de pod (celui forké)
   • compare : la branche que vous voulez fusionner (pseudogit/feature-nouveau_truc_bien par exemple)
4. Terminer en cliquant sur "Create pull request"

Cela va faire une demande de fusion qui sera traité par les responsables du dépot. N'hésitez pas à commenter vos Pull Requests pour décrire les ajouts et/ou modifications effectués et leurs objectifs !

Normes de développement pour les nouvelles fonctionnalités

Quand vous développez une nouvelle fonctionnalité il est nécessaire de respecter quelques normes par soucis d'organisation du code

Le principe

Le projet Pod est amené à acceuillir de nouvelles fonctionnalités durant son développement. Cependant elles ne sont pas forcémment utilisés par tout les établissements, car cela varie selon les besoins de chacuns. Ainsi une règle importante à suivre durant le développement d'une nouvelle fonctionnalité est la suivante :

Ajouter une fonctionnalité n'est pas l'imposer.

Cela veut dire que Pod doit pouvoir être fonctionnel, même si la nouvelle fonctionnalité développée n'est pas activé ou configuré. De ce fait il va falloir mettre en place un moyen de controler la portée de la nouvelle fonctionnalité sur le code général de l'application.

Les variables de configuration

Une chose simple à faire est de définir pour l'application une/des variables constantes dans les fichiers de configuration (settings.py et settings_local.py) pour contrôler l'activation et la desactivation de la fonctionnalité. Cela peut prendre cette forme :

Fichier settings_local.py

NEW_APPLICATION = True #False

Pour activer ou non la nouvelle fonctionnalitée.

Fichier python existant modifié par votre application

NEW_APPLICATION = getattr(settings, 'NEW_APPLICATION', False)

Pour chercher la variable dans le fichier de settings. Obtient sa valeur et si la variable n'existe pas lui donne "False" par défaut. Ainsi cela prévient tout type d'erreurs concernant des variables manquantes (Si l'on a pas envie de la fonctionnalité, on peut décider de ne pas ajouter du tout les variables dans le fichier settings pour plus de visibilité).

Cette variable NEW_APPLICATION peut maintenant être utilisé dans le code de Pod pour controler le comportement de la nouvelle fonctionnalité selon si elle est activée ou non). Cela prend souvent la forme d'une condition :

if NEW_APPLICATION :
    <...>

Si notre nouvelle fonctionnalité touche aux templates, une étape supplémentaire est requise pour utiliser notre variable :

Fichier settings.py

TEMPLATE_VISIBLE_SETTINGS = (
        ...,
        NEW_APPLICATION
)

Ainsi notre variable NEW_APPLICATION est chargée au lancement du serveur et peut-être utilisée dans les templates pour générer du code html/js/css selon sa valeur. Par exemple :

{% if NEW_APPLICATION %}
    <div id=...>
{% endif %}

Ainsi on intégre aux pages du contenu uniquement quand la fonctionnalité est activée.

Enfin, si la nouvelle fonctionnalité contient des nouvelles pages, donc des nouveaux urls on doit ajouter ces urls uniquement si elle est activée. Cela permet d'éviter de tomber sur des urls qui ménent à des erreurs si l'application est désactivée.

Fichier urls.py

if settings.NEW_APPLICATION :
    urlpatterns += [
        <url>
    ]

On ajoute l'url de l'application dans l'ensemble des urls de Pod uniquement si elle est activée.

Par soucis de fonctionnement, les urls relatives aux channels (chaînes) doivent être chargées en dernier. Si vous ajoutez des urls mettez les avant.

Voici tout ce qu'il faut retenir pour controler la portée de la nouvelle application selon si elle est activée ou non.

Le format du code Python

Le projet Pod suit la convention "PEP8" (PEP8). Il est nécessaire de formater le code python selon ce modèle.
Des logiciels d'édition de code comme par exemple Sublime Text disposent de plugins d'auto-format pour le PEP8 (Plugin pour SublimeText)

Evitez si possible quand vous écrivez du code de mélangez les tabulations et les espaces pour l'indentation. Cela risque de poser des problèmes entre les éditeurs de code

La traduction

De préférence il est conseillé de créer votre nouvelle fonctionnalité en anglais puis de proposer une traduction, si nécessaire, en Français minimum. Cette procédure est à suivre, par exemple, si il y a des ajouts au niveau des templates.

Pour rappel la procédure à suivre pour traduire votre travail se trouve dans la documentation d'installation : Traduction