Bien commencer avec mviewer¶
Préparer votre environnement de travail¶
Si vous débutez, nous vous conseillons de créer un dossier unique nommé « git ». Nous installerons ensuite Git et le terminal Git Bash pour passer les commandes à Git.
Sur Windows:
C:\Users\jean\Documents\git
Sur Ubuntu/Debian (autre):
/home/user/jean/git
Le code mviewer sera par la suite placé dans un répertoire « mviewer »:
Exemple: C:\Users\jean\Documents\git\mviewer
Télécharger ensuite Git et installez le tout. Le terminal Git Bash sera installé en même temps.
Git Bash vous permettra de réaliser les commandes qui suivront.
Travailler avec un fork¶
Règle générale : ne jamais modifier la branche MASTER.
La branche master est une branche « mirroir » de la branche master du code initial (mviewer/mviewer).
C’est votre point de départ pour tout nouveau travail et tout nouveau travail doit repartir d’une base à jour et propre.
Nous recommandons de créer une branche à partir de la branche master à jour pour chaque nouveau travail.
La section qui suit vous donnera la procédure pour obtenir votre fork.
Récupérer les sources (fork)¶
Pour bien débuter, nous vous recommandons de réaliser un fork vers votre espace GitHub.
Prérequis
Disposer d’un compte GitHub
Avoir les droits de création sur ce compte
Être connecté sur GitHub
Procédure
Sur la page GitHub du mviewer cliquer sur « Fork » en haut à droite.
Choisissez ensuite le compte vers lequel réaliser votre fork.
Vous détenez maintenant un fork disponible à l’adresse : https://github.com/MON_ORG/mviewer MON_ORG étant à remplacer par le nom de votre compte GitHub.
Votre fork contient nativement les mêmes branches à l’identique, dont la branche master.
Vous pourrez créer des nouvelles branches et modifier le code sans impacter le code natif du repository inital (mviewer/mviewer).
Ouvrez Git Bash
Allez sur le repository mviewer GitHub et cliquez sur « clone or download ». Copier ensuite l’URL dans la commande suivante.
Réalisez un clone (copie) du code mviewer sur votre ordinateur en collant l’URL précédente:
git clone https://github.com/MON_ORG/mviewer.git
Gestion des droits¶
Vous pouvez gérer les droits de votre repository pour les utilisateurs, développeurs et autres personnes disposant d’un compte GitHub.
Pour cela, cliquez en haut dans « Settings » et accédez à gauche à l’onglet « Collaborators & team ».
Créer une branche¶
Vous pouvez créer une branche sur GitHub directement ou avec Git.
Pour créer une branche su GitHub.
Cliquez sur le bouton de la liste Branch:(nom de branche)
Choisissez la branche de départ (master) dans la liste des branches disponibles
Cliquez à nouveau sur le bouton de la liste Branch:(nom de branche)
Dans le champ de recherche, saisissez le nom de votre nouvelle branche (*).
Cliquez ensuite sur « Create Branch: (nom de votre branche) »
Vous avez maintenant une nouvelle branche.
Pour récupérer cette nouvelle branche dans votre dépôt Git, suivez la procédure qui suit:
Positionnez-vous dans votre dossier ../git/mviewer/:
Synchronisez votre dossier git:
git fetch
Positionnez-vous dans votre dossier mviewer (le dossier créé par la commande “git clone”):
git pull
Si vous souhaitez changer de branche, saisissez cette commande:
git checkout NOM_DE_MA_BRANCHE
Récupérer les nouveautés de la branche¶
Pour mettre à jour votre dépôt (dossier) local mviewer (/git/mviewer) réalisez la commande:
git pull
Vous travaillerez maintenant sur la nouvelle branche de votre choix. Chaque nouvelle mise à jour de la branche master de votre fork devra être reportée sur cette branche aussi souvent que possible.
Pour mettre à jour la branche master de votre fork, nous devons définir en premier une « source distante » (upstream).
(*) Attention : Choisissez un nom permettant d’identifier rapidement cette branche pour vous et votre équipe.
Définir un upstream¶
Pour mettre à jour la branche master depuis le code de mviewer, vous devrez indiquer quelle est la « source distante » (upstream). Votre « origin » sera votre votre repository mviewer (fork).
Voici la manipulation.
Définir un upstream:
git remote add upstream https://github.com/mviewer/mviewer
Observer que vous avez bien un upstream:
git remote -v > origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) > origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) > upstream https://github.com/mviewer/mviewer.git (fetch) > upstream https://github.com/mviewer/mviewer.git (push)
Bravo ! Mettons maintenant à jour votre branche master.
Mettre à jour votre fork - master¶
Attention : assurez-vous d’avoir réalisé l’étape précédente avant celle-ci.
Vous devrez un jour mettre à jour votre branche master au sein de votre fork. Faites ainsi :
Avec Git Bash ou votre terminal, positionnez-vous dans votre dossier mviewer (dossier récupéré via le clone):
cd C:\Users\jean\Documents\git\mviewer
Vérifiez que vous avez bien un upstream qui pointe vers https://github.com/mviewer/mviewer.git (voir l’étape précédente).
Positionnez vous sur la branche master:
git checkout origin/master
Synchronisez vous avec la source distante:
git fetch upstream
Remplacez votre branche master (origin) par celle de mviewer (upstream):
git reset --hard upstream/master
Poussez ensuite ce code récupéré depuis mviewer (upstream) vers votre branche master (origin):
git push origin master --force
Organisation des fichiers de carte¶
Rgèle générale
Ne JAMAIS modifier les fichiers du coeur.
Les fichiers du coeur sont tous les fichiers que vous obtenez nativement avec un clone de départ.
Nous vous recommandons d’intégrer la structure décrite dans cette section afin de simplifier vos manipulations de fichier :
Créer un répertoire « apps » à la racine du mviewer.
Positionner tous les fichiers de configuration XML à la racine du répertoire apps:
Exemple : C:\Users\jean\Documents\git\mviewer\apps\ma_carte.xml
Créer un dossier par fichier de configuration que nous appellerons « dossiers de carte »:
Exemple : C:\Users\jean\Documents\git\mviewer\apps\ma_carte\
Pour chaque dossier de carte, vous devrez créer les dossiers : templates, customcontrols, customlayers, data, sld, css, img.
Pour notre fichier de config « ma_carte.xml », nous aurons donc cette structure:
/apps
├── ma_carte.xml
└── ma_carte
├── customcontrols
├── customlayers
├── data
├── css
├── sld
├── img
└── templates
Vous placerez dans ces dossiers les données (geojson), les customcontrols (js), les cunstomlayers (js) ainsi que les template mustache (js). Vous prendrez en compte la localisation de ces fichiers dans le fichier de configuration XML en donnant les bons chemins d’accès.
Organisation des autres fichiers¶
Créer un répertoire « common » à la racine du répertoire « apps » (/apps/common/)
Créer un dossier js, css, img, lib
Créer un dossier basemaps, logo, legend, credit dans /img (/apps/common/img/)
On obtiendra donc cette structure:
/apps
├── common
└── js/
├── css/
├── lib/
└── img/
├── legend/
├── logo/
├── credit/
└── basemap/
├── ma_carte.xml
└── ma_carte
├── customcontrols
├── customlayers
├── data
└── templates
Vous placerez tous les fichiers que vous avez créés ou modifiés dans ces dossiers au sein de /apps/common. Vous prendrez en compte la localisation de ces fichiers dans le fichier de configuration XML en donnant les bons chemins d’accès.
URL de carte¶
Il vous faudra prendre en compte le dossier « apps » dans vos URLs de carte ainsi:
http://kartenn.region-bretagne.fr/kartoviz/?config=apps/aide-droit-carte.xml
Addons¶
Si vous souhaitez enrichir vos cartes de fonctionnalités (isochrones, recherches, filtres temporels…) vous pouvez dupliquer cet addon dans tous les dossiers de carte.
Vous pouvez aussi créer un dossier « addons » dans le répertoire common et y ajouter la structure nécessaire (customlayers, customcontrols) pour être réexploitable par toutes les cartes :
Voici exemple d’organisation de fichier avec un addon « Isochrone »:
/apps
├── common
└── js/
├── css/
├── lib/
├── addons/
└── isochrone
├── customlayers
├── customcontrols
└── img/
├── legend/
├── logo/
├── credit/
└── basemap/
Le dossier « apps » étant votre dossier de travail, vous pouvez l’organiser selon vos besoins.
Participer à la communauté¶
Pour apporter une correction d’anomalie ou une évolution, nous vous recommandons d’aller à la la page « Contribuer ».
Bonnes pratiques de développements¶
Commits
Lorsque vous réalisez des commits, séparez les commits de style des commits de code.
Un commit de style comprend :
Suppression / ajout d’un espace
Suppression / ajout d’un saut de ligne
Tout ce qui n’est pas du code
Un commit de code comprendra à l’inverse :
Une modification sur une syntaxe
Une modification sur une fonction
Une modification sur un nom de variable
Tout ce qui n’est pas du style
Encodage
L’encodage a utiliser est l’UTF-8.
Formatage
Lors de vos développements, inspectez le formatage du code initial :
Le nombre d’espace pour indenter
La présence d’espace avant et après les parenthèses
La présence d’espace avant ou après les opérateurs logiques (==, <, >, ||, &&)
Le nombre de saut de lignes avant ou après une fonction, un bloc de clode, etc…
autres
Méfiez-vous de votre éditeur de code. Pensez à désactiver les plugins ou à configurer les règles de formatage.
Respectez ensuite ce formatage.
Commentaires
Un code commenté est un code compréhensible par tous. Nous recommandons très fortement d’utiliser les commentaires. Mieux vaut trop de commentaires que pas assez.
Commentaires JavaScript:
// ceci est un commentaire sur une ligne /* Ceci est un commentaire sur plusieurs lignes*/
Commentaire CSS:
/*Je suis un commentaire CSS*/
Commentaire HTML:
<!--Je suis un commentaire HTML-->
Pour les fonctions ou méthodes JavaScript, nous recommandons d’ajouter en commentaire :
Ce que fait cette fonction ou méthode
Les paramètres en entrée
Le résultat attendu et ce qui est retourné en sortie
Les indésirables
Nous déconseillons les affichages d’informations qui ne sont utiles qu’aux développeurs (console.log, alert…).
Editeur de code
Il n’y a pas d’obligation et vous êtes libre d’en choisir un.
Notepadd++
Sublime
Visual Studio Code
Atome
autre
Informations Git & GitHub¶
Vous trouverez plus d’information sur la page « Travailler avec Git et GitHub ».
Vous trouverez notamment de la documentation dans la partie « Documentation ».