Mon projet pour les nuls

all: html wiki

html:

	pandoc user_guide.md -o user_guide.html -s --toc	

wiki:

	pandoc user_guide.md -o user_guide.wiki -t textile -s --toc

clean:

	rm -f user_guide.html user_guide.wiki

% Documentation Utilisateur de la Forge CBP

% Forge du Centre Blaise Pascal

% Décembre 2012

# 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.

# Ouverture d'un compte utilisateur

## 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.

## Utilisateur extérieur

Un utilisateur ne disposant pas de compte ENS doit s'enregistrer (en remplissant le formulaire accessible en cliquant sur *S'enregistrer*). Le compte doit ensuite être activé manuellement par les administrateurs.

# 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.cbp.ens-lyon.fr> en précisant :

- Le nom du projet

- L'identifiant du projet

- Le gestionnaire de code source préféré (SVN ou Git)

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).

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.

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.

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

## Récupération initiale du dépôt

Un membre *developper* d'un projet accède au dépôt de la façon suivante :

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

**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.

Voici une commande pour créer l'archive subversion originelle à partir d'un répertoire existant :

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

## 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.

## 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 mv/rm/cp`  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

## 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)

# Utilisation d'un dépôt Git

## Initialisation du dépôt

Lorsque un projet utilisant un dépôt Git à été validé, un des membres *developer* ou *manager* du projet doit activer ce dépôt en faisant le commit initial:

    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

## Accès au dépôt Git

1.    Depuis la station d'un *developer* (ou d'un *reporter* en lecture seule), en HTTPS

    - Clonage du dépôt

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

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

            git config  --add http.sslVerify false

    - Ensuite, utilisation usuelle de git

            git pull

            #modifications

            git add <fichiers modifiés>

            git commit

            git push

2.    Depuis la station d'un *developer* (ou d'un *reporter* en lecture seule), en HTTP

    - Clonage du dépôt

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

    - Ensuite, utilisation usuelle de git

            git pull

            #modifications

            git add <fichiers modifiés>

            git commit

            git push

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

    - Clonage du dépôt

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

    - Ensuite, utilisation usuelle de git

            git pull

            #modifications

            git add <fichiers modifiés>

            git commit

            #git push sera rejeté

## 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)

# 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/)).

Il existe la gestion de versions pour les Wiki.

## 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 :

    {{html(

    .....

    )}}

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):

    {{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>)}}

# 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ées*).

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

# 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.

## Configuration du projet pour l'activation de Webdav

1.    Activer le module Webdav :

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

2.    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

## Accès Webdav

Le partage Webdav est accessible à l'URL <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).