# Contribuer au code source

## Contenu
* [Prérequis](#pr-requis)
* [Créer sa copie du projet](#cr-er-sa-copie-du-projet)
* [Contribuer au code](#contribuer-au-code)
* [Créer un nouveau skin](#cr-er-un-nouveau-skin)

## Prérequis

Les équipes de développement AFI et Biblibre utilisent le [sytème de gestion de développement](https://fr.wikipedia.org/wiki/Forge_%28informatique%29) libre [GitLab](https://www.gitlab.com) et le [système de gestion de version](https://fr.wikipedia.org/wiki/Gestion_de_versions) [Git](http://www.git-scm.com). Ce document décrit l'utilisation minimale nécessaire de ces deux outils pour pouvoir contribuer au code des projets maintenus par AFI et Biblibre. Néanmoins nous vous invitons à lire le livre [Pro Git](http://git-scm.com/book/fr).

Nous hébergeons les codes sources des projets sur une instance de GitLab accessible à l'URL https://git.afi-sa.fr. Les projets publics sont accessibles sans compte à l'URL https://git.afi-sa.fr/public.


## Créer sa copie du projet

### Créer un compte gitlab

Depuis la page [Sign Up](http://git.afi-sa.fr/users/sign_up) vous pouvez créer votre compte. Un mail sera automatiqument envoyé pour vous confirmer l'accès. 


### Cloner le projet

Une fois connecté, depuis la [page du project OPACCE](http://git.afi-sa.fr/afi/opacce), cliquez sur le bouton **Fork repository**.

Cela vous créera une copie intégrale du projet, accessible publiquement à l'adresse http://git.afi-sa.fr/mon_compte/opacce.


L'accès SSH au dépôt git est donné sur la page d'accueil de votre projet. Par exemple git@git.afi-sa.fr:mon_compte/opacce.git


### Installer l'accès SSH

Le poussage de modifications sur gitlab requiert un accès ssh.  Sur [la page de modification de votre profil](http://git.afi-sa.fr/profile), à l'onglet [SSH Keys](http://git.afi-sa.fr/profile/keys), le lien [Add SSH Key](http://git.afi-sa.fr/profile/keys/new) permet d'ajouter une clé.

#### Créer et déclarer sa clé

Si vous posséder déjà une clé sur votre poste de travail dans **~/.ssh/id_rsa.pub**, copiez le contenu.

Sinon pour [générer une clé SSH sur votre poste de travail](http://git.afi-sa.fr/help/ssh), utilisez la commande suivante:
```bash
ssh-keygen -t rsa -C "addresse_email@domaine.ext"
```

et pour afficher le contenu:
```bash
cat ~/.ssh/id_rsa.pub
```

#### Configurer l'accès SSH

L'accès SSH passe par le port **2950**. Créez ou modifiez le fichier **~/.ssh/config** pour y ajouter les lignes suivantes:
```
Host git.afi-sa.fr
  Hostname git.afi-sa.fr
  Port 2950
  User git
  IdentityFile ~/.ssh/id_rsa

```

## Contribuer au code

### Installer sa copie de l'OPAC

L'installation se déroule comme décrit [dans la procédure d'installation](INSTALL.fr.md), excepté que la commande pour cloner le projet décrite dans la section [Récupération des sources](INSTALL.md#Récupération-des-sources) utilise votre propre dépôt:
```bash
cd /var/www
git clone git@git.afi-sa.fr:mon_compte/opacce.git
```

### Faire des modifications et les pousser vers gitlab

Une fois quelques modifications effectuées, l'envoi des données se fait en deux temps.

1. Commit des modifications sur votre machine en local
```bash
git commit -a -m "Commentaires des modifications"
```

2. Pousser les modifications de votre branche master vers gitlab (origin):
```bash
git push origin master
```

Pour plus de détails, consultez [Pro Git](http://git-scm.com/book/fr)


### Proposer les modifications aux mainteneurs de la version officielle

Sur la page de votre projet GitLab, onglet **Merge Requests**, cliquez sur le lien **+ New Merge Request** et remplissez les différents champs pour décrire vos modifications. 


### Récupérer les dernières modifications de la version officielle

Tout d'abord, il faut déclarer le dépôt de la version officielle (upstream) dans votre projet local:
```bash
git remote add upstream git@git.afi-sa.fr:afi/opacce.git
```

Ceci fait, vous pouvez fusionner les modifications dans votre branche:

```bash
# Télécharge toutes les nouvelles modifications du dépôt distant
git fetch upstream master
# Fusionne les nouvelles modifications dans votre répertoire
git merge upstream/master
# Pousse la fusion sur gitlab
git push origin master
```



## Créer un nouveau skin

### Création

Se placer dans le répertoire skins à la racine de l'OPAC et recopier le skin modele

```bash
cd skins
cp -a ../public/opac/skins/modele mon_skin
```

Aller dans la configuration d'un profil de l'OPAC, le nouveau skin devrait être disponible dans le sélecteur de thème.



### Sauvegarde sur GitLab

Créer le projet sur [GitLab](https://git.afi-sa.fr) pour stocker les sources. Par exemple https://git.afi-sa.fr/mon_compte/mon_skin.

Aller dans le répertoire mon_skin et initialiser le dépôt:

```bash
cd mon_skin
git init
git remote add origin -t master git@git.afi-sa.fr:mon_compte/mon_skin.git
git add *
git commit -m "Premier commit"
git push origin master
```

Ceci fait, les nouveaux fichiers devraient être accessibles sur https://git.afi-sa.fr/mon_compte/mon_skin/files


### Description des répertoires

* **css/** contient le fichier global.css sur lequel travailler. Les autres fichiers sont destinés à devenir obsolètes.
* **images/** les icônes, dont **images/support/** pour les types de support. Les fichiers doivent être nommés comme suit: **support_id_.png**, par exemple **support_1.png** pour les livres.
* **templates/** les modèles de rendu boite de la page d'accueil. Les fichiers doivent êtres nommés en séparant les mots par des tirets bas **_**, qui seront dans la configuration des boîtes **Style de boîte**. Chaque modèle de boîte peut inclure les tags **{TITRE}**, **{RSS}**, **{CONTENU}**. Pour avoir un rendu conditionnel, le fichier peut inclure les conditions **{IF-TITRE}**, **{IF-RSS}**, **{IF-CONTENU}** suivi de la balise **{ENDIF}**

```html
<div class="right-box">
	<div class="right-box-inner">
		{IF-TITRE}
		<div class="header">
			<div><h1>{TITRE}</h1></div>
			<div class="rss">{RSS}</div>
		</div>
		{ENDIF}
		<div class="content">
			{CONTENU}
		</div>
	</div>
</div>
```


Tous les fichiers de vue du répertoire **application/modules/opac/views/scripts** peuvent être redéfinis dans un répertoire html. Les principaux sont:
* **footer.phtml** pour le pied de page
* **banniere.phtml** pour l'en-tête
* **skin_head.phtml** pour rajouter des éléments dans la balise **head** du site
* **accueil.phtml** pour la page d'accueil
* **contenu.phtml** pour les autres pages