Mon projet pour les nuls

h1. Introduction et termes fréquemment employés

La forge du Centre Blaise Pascal (CBP) utilise l'application de gestion de projet "Redmine":http://www.redmine.org. La documentation utilisateur de cette application est disponible à "cette page":http://www.redmine.org/projects/redmine/wiki/User_Guide.

Voici une description des termes couramment employés dans ce système :

* _Projet_. C'est un espace de travail, lié à un sujet déterminé, mis à disposition d'une équipe d'utilisateurs _membres_.

** Un projet peut être _Public_ ou _Privé_. Un projet _Privé_ n'est visible que par ses _membres_. Un projet _Public_ est visible par tout le monde, mais ne peut pas être modifié par les utilisateurs non membres.

** Un projet peut contenir des sous projets.

* Les différents rôles des utilisateurs membres d'un projet sont _Manager_, _Developer_ et _Reporter_. Les utilisateurs membres d'un projet peuvent avoir différents rôles dans ce projet. À chaque rôle est associé différentes permissions :

** Les membres _Manager_ d'un projet peuvent le configurer, y ajouter des nouveaux membres, modifier son contenu.

** Les membres _Developer_ d'un projet peuvent modifier son contenu.

** Les membres _Reporter_ d'un projet peuvent accéder à son contenu et émettre des requêtes.

h1. Ouverture d'un compte utilisateur

h2. Utilisateur disposant d'un compte à l'ENS Lyon

Un utilisateur disposant d'un compte à l'ENS Lyon n'a pas besoin de créer un compte sur la forge. Il doit directement cliquer sur _Connexion_ et entrer son login et mot de passe ENS (il n'est pas nécessaire de cliquer sur _S'enregistrer_). Lors de cette première connexion, le compte est automatiquement crée sur la forge.

h2. Utilisateur extérieur

Un utilisateur ne disposant pas de compte ENS doit contacter son chef de projet et lui indiquer l'identifiant et l'adresse de courrier électronique. Le chef de projet demande alors aux administrateurs de la forge de créer le compte local en leur adressant un courriel à "admin-forge@ens-lyon.fr":mailto:admin-forge@ens-lyon.fr

h1. Ouverture d'un projet

La création d'un nouveau projet n'est possible que par les administrateurs de la forge. Pour ouvrir un projet, l'utilisateur doit envoyer un mail à "admin-forge@ens-lyon.fr":mailto:admin-forge@ens-lyon.fr en précisant :

* Le nom du projet

* L'identifiant du projet

* Le gestionnaire de code source préféré (SVN, Git ou Mercurial)

Le nom du projet est libre. C'est lui qui est visible dans l'interface. Par exemple, "Mon projet pour les nuls".

L'identifiant est soumis aux contraintes suivantes :

* Longueur comprise entre 1 et 100 caractères

* Seuls les lettres minuscules (a-z), chiffres, tiret et souligné sont autorisés

* Une fois sauvegardé, l'identifiant ne pourra plus être modifié (il sert comme identifiant dans la base de données).

> +*Attention, si le projet utilise un dépôt Git, son identifiant NE doit PAS contenir le caractère souligné.*+

L'utilisateur ayant fait la demande d'ouverture de projet est désigné comme _manager_ du projet et reçoit un mail de confirmation. Il peut ensuite ajouter des utilisateurs en tant que membres du projet.

Pour cela, il faut se rendre sur la page _Configuration_, puis _Membres_. Il appartient au manager de choisir le rôle des membres ainsi ajoutés (reporter, developer ou manager).

Pour plus d'information sur la configuration du projet, se référer à "cette page":http://www.redmine.org/projects/redmine/wiki/RedmineProjectSettings de la documentation Redmine.

h1. Création d'un dépôt (Git, Mercurial ou Subversion)

La création automatisée d'un dépôt (un seul par projet, en mode automatique) est activée au travers de l'interface d'administration du projet :

* dans l'onglet « Configuration » du projet, cliquez sur l'onglet « Dépots » ;

* cliquez sur le lien « Nouveau dépôt » ;

* dans la fenêtre de création :

** sélectionnez le gestionnaire de dépôt (champ SCM), pour le moment, seuls Git, Mercurial et Subversion sont véritablement actifs,

** cochez la boîte « Dépôt principal » ;

** renseignez le champ « URL » :

*** pour un dépôt Git : /var/git/identifiant_projet (attention, pas de caractère souligné dans un identifiant de projet pour dépôt GIT),

*** pour un dépôt Mercurial : /var/hg/repos/identifiant_projet,

*** pour un projet Subversion : file:///var/svn/identifiant_projet ;

** laissez vides tous les autres champs ;

** sauvegardez.

Il est impératif que vous respectiez scrupuleusement les consignes ci-dessus pour que :

* la création du dépôt se fasse correctement ;

* les outils de visualisation des versions dans l'interface Redmine fonctionnent eux aussi correctement.

Le dépôt ne sera pas créé instantannément. Un programme déclenché toutes les 10 minutes assure cette tâche. 

Si, au bout d'une demi-heure, vous ne pouvez toujours pas accéder au dépôt selon les modalités décrites ci-dessous, vérifiez les informations de configuration et, si le problème persiste, contactez les "adminstrateurs":mailto:admin-forge@listes.ens-lyon.fr.

Si vous souhaitez une configuration « non standard » (p. ex. des dépôts multiples) contactez les "administrateurs":mailto:admin-forge@listes.ens-lyon.fr

h1. Utilisation d'un dépôt Subversion (SVN)

h2. Récupération initiale du dépôt

Il est possible pour membre _manager_ ou _developper_ de créer l'archive subversion originelle à partir d'un répertoire existant :

<pre>svn --username $USER import <Mon répertoire>/ https://forge.cbp.ens-lyon.fr/svn/$PROJECT_ID/ -m 'Importation de la version originelle'</pre>

L'accès au dépôt s'effectue de la façon suivante :

<pre>svn --username $USER checkout http://forge.cbp.ens-lyon.fr/svn/$PROJECT_ID</pre>

*Note*: \$USER est le login de l'utilisateur. Il doit être membre du projet si le projet est privé. $PROJECT_ID est l'identifiant du projet.

h2. Envoi d'un mail lors de modification dans un dépôt SVN

Il est possible qu'un mail soit envoyé à chaque membre d'un projet lors d'un commit dans le dépôt SVN. Pour activer cette fonctionnalité, en faire la demande lors de l'ouverture du projet ou ultérieurement.

En outre, dans la page Activité du projet apparait un rappel de toutes les modifications (ainsi qu'un extrait des messages de commit).

h2. Utilisation de SVN (lorsqu'on connait CVS)

Les améliorations les plus importantes de SVN par rapport à CVS sont les suivantes :

* Déplacer / Renommer / Supprimer les fichiers en les conservant dans l'historique

* Support transparent des fichiers binaires

* Modifications appliquées par projet et non plus par fichier

* Gestion des trunk/branches/tags : Le répertoire trunk contient la version courante du projet, branches contient les "forks" éventuels du projet, tags contient des versions "gelées" du projet (release, etc.)

Les commandes usuelles :

|_. Commande|_. Fonction|

|@svn checkout@|Rapatrie un dépôt|

|@svn commit@|Applique les modifications locales|

|@svn diff@|Montre les modifications entre deux révisions dans le projet|

|@svn update@|Récupère les dernières modifications d'un projet|

|@svn add/mv/rm/cp@|Ajoute/Déplace/Supprime/Copie un fichier|

|@svn status@|Affiche le status des modifications en cours|

|@svn revert@|Retourne à une version précédente d'un fichier|

h2. Plus d'information

* La page de documentation Redmine sur les "dépôts":http://www.redmine.org/projects/redmine/wiki/RedmineRepository.

* La page Wikipedia sur "Subversion":http://fr.wikipedia.org/wiki/Apache_Subversion

h1. Utilisation d'un dépôt Git

h2. Initialisation du dépôt

Lorsque un projet utilisant un dépôt Git a été validé, un des membres _developer_ ou _manager_ du projet doit activer ce dépôt en faisant le commit initial:

<pre>

GIT_SSL_NO_VERIFY=true git clone https://$USERNAME@forge.cbp.ens-lyon.fr/git/$PROJECT_ID

#Ou en HTTP

#git clone http://$USERNAME@forge.cbp.ens-lyon.fr/git/$PROJECT_ID

cd $PROJECT_ID

git add .

git commit -m "Repository creation" --allow-empty

GIT_SSL_NO_VERIFY=true git push origin master

</pre>

h2. Accès au dépôt Git

* Depuis la station d'un _developer_ (ou d'un _reporter_ en lecture seule), en HTTPS

Clonage du dépôt

<pre>

GIT_SSL_NO_VERIFY=true git clone https://$USERNAME@forge.cbp.ens-lyon.fr/git/$PROJECT_ID

</pre>

Désactivation de la vérification du certificat SSL pour de bon

<pre>

git config  --add http.sslVerify false

</pre>

Ensuite, utilisation usuelle de git

<pre>

git pull

#modifications

git add <fichiers modifiés>

git commit

git push

</pre>

* Depuis la station d'un _developer_ (ou d'un _reporter_ en lecture seule), en HTTP

Clonage du dépôt

<pre>

git clone http://$USERNAME@forge.cbp.ens-lyon.fr/git/$PROJECT_ID

</pre>

Ensuite, utilisation usuelle de git

<pre>

git pull

#modifications

git add <fichiers modifiés>

git commit

git push

</pre>

* En accès anonyme, uniquement si l'option _Public_ du projet à été activée.

Clonage du dépôt

<pre>

git clone http://forge.cbp.ens-lyon.fr/git/$PROJECT_ID

</pre>

Ensuite, utilisation usuelle de git

<pre>

git pull

#modifications

git add <fichiers modifiés>

git commit

#git push sera rejeté

</pre>

h2. Plus d'information

* La page de documentation Redmine sur les "dépôts":http://www.redmine.org/projects/redmine/wiki/RedmineRepository.

* La page Wikipedia sur "Git":https://fr.wikipedia.org/wiki/Git

h1. Utilisation d'un dépôt Mercurial

h2. Accès au dépôt

* Depuis la station d'un _developer_ (ou d'un _reporter_ en lecture seule), en HTTPS

Clonage du dépôt

<pre>

hg clone https://$USERNAME@forge.cbp.ens-lyon.fr/hg/$PROJECT_ID

</pre>

Ensuite, utilisation usuelle d'hg

<pre>

hg pull

#modifications

hg add <fichiers>

hg commit

hg push

</pre>

* En accès anonyme, uniquement si l'option _Public_ du projet à été activée.

Clonage du dépôt

<pre>

hg clone http://forge.cbp.ens-lyon.fr/hg/$PROJECT_ID

</pre>

h1. Wiki

Le wiki est certainement la partie la plus importante du projet, point de concentration de tous les documents électroniques directement moissonnables par le moteur de recherche intégré.

Pour le Wiki, "formatage de base":https://forge.cbp.ens-lyon.fr/redmine/help/wiki_syntax.html et "formatage étendu":https://forge.cbp.ens-lyon.fr/redmine/help/wiki_syntax_detailed.html fournissent tout ce qu'il faut pour bien formater (la syntaxe utilisée est "TexTile":http://textile.thresholdstate.com/).

Les Wiki sont versionnés par défaut.

h2. Intégration de pages HTML statiques

Il est possible d'intégrer des pages HTML statiques au wiki grâce au plugin Redmine "Wiki HTML":https://github.com/mexitek/redmine_wiki_html_util.

Pour cela, il faut intégrer le code HTML de la page à intégrer à l'intérieur des balises suivantes :

<pre>

{{html(

.....

)}}

</pre>

Le style CSS appliqué à la page hérite de celui du Wiki. Pour supprimer ce style, on peut utiliser la macro suivante (qui supprime la classe wiki des balises div):

<pre>

{{html(<script>var divs = document.getElementsByTagName('div'); for (var i = 0, c = divs.length ; i < c ; i++) {if (divs[i].className=='wiki wiki-page') {divs[i].className='';};}</script>)}}

</pre>

h1. Demandes Redmine

Les _demandes_ sont utilisées dans les projets Redmine pour permettre aux utilisateurs d'un projet de signaler des problèmes (_Bug_), de demander de l'aide (_Support_), etc, via l'ouverture de _tickets_.

Il est possible pour les utilisateurs membres d'un projet de recevoir un mail d'alerte lors de la création ou la modification d'un _ticket_ (par défaut, uniquement pour ceux _observés_).

Pour plus d'information, ce référer à la documentation Redmine sur les "demandes":www.redmine.org/projects/redmine/wiki/RedmineIssues

h1. Utilisation de Webdav

Webdav permet l'accès à distance aux _Fichiers_, aux _Documents_ et au contenu d'un dépôt Subversion d'un fichier.

h2. Configuration du projet pour l'activation de Webdav

# Activer le module Webdav :

** Depuis l'interface de Redmine aller dans Projet, Configuration, Modules, Activer Webdav, Sauvegarder.

# Configurer le module :

** Depuis l'interface de Redmine aller dans Projet, Configuration, Webdav.

** Activer ou désactiver Fichiers/Documents/Dépôts au besoin. L'accès au dépôt ne fonctionne que pour un dépôt SVN hébergé sur le serveur.

** Attention à désactiver Dépôt exclusif pour permettre l'accès aux Fichiers et Documents

h2. Accès Webdav

Le partage Webdav est accessible à l'URL "http://forge.cbp/redmine/webdav/$PROJECT_ID":http://forge.cbp/redmine/webdav/$PROJECT_ID (sous nautilus, on peut faire Ctrl+L et entrer @dav://forge.cbp/redmine/webdav/$PROJECT_ID@ pour créer un point de montage). L'accès au partage d'un projet à non membre est possible si le projet est public.

Les permissions de lecture / écriture sont respectées (écriture pour _developer_ ou _manager_ uniquement).