CONTRIB.fr.md 6.4 KB
Newer Older
Laurent's avatar
Laurent committed
1 2
# Contribuer au code source

3
## Contenu
Laurent's avatar
Laurent committed
4 5 6 7
* [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)
Laurent's avatar
Laurent committed
8 9

## Prérequis
Laurent's avatar
Laurent committed
10 11 12

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

Laurent's avatar
Laurent committed
13 14 15 16 17 18 19
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

20
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. 
Laurent's avatar
Laurent committed
21 22 23 24


### Cloner le projet

25
Une fois connecté, depuis la [page du project OPACCE](http://git.afi-sa.fr/afi/opacce), cliquez sur le bouton **Fork repository**.
Laurent's avatar
Laurent committed
26 27 28 29 30

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
Laurent's avatar
Laurent committed
31 32


Laurent's avatar
Laurent committed
33
### Installer l'accès SSH
Laurent's avatar
Laurent committed
34

Laurent's avatar
Laurent committed
35
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é.
Laurent's avatar
Laurent committed
36

Laurent's avatar
Laurent committed
37 38
#### Créer et déclarer sa clé

Laurent's avatar
Laurent committed
39
Si vous posséder déjà une clé sur votre poste de travail dans **~/.ssh/id_rsa.pub**, copiez le contenu.
Laurent's avatar
Laurent committed
40

Laurent's avatar
Laurent committed
41 42 43 44
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"
```
Laurent's avatar
Laurent committed
45

Laurent's avatar
Laurent committed
46 47 48 49
et pour afficher le contenu:
```bash
cat ~/.ssh/id_rsa.pub
```
Laurent's avatar
Laurent committed
50

Laurent's avatar
Laurent committed
51 52 53 54 55 56 57 58
#### 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
Laurent's avatar
Laurent committed
59
  IdentityFile ~/.ssh/id_rsa
Laurent's avatar
Laurent committed
60 61

```
Laurent's avatar
Laurent committed
62

Laurent's avatar
Laurent committed
63 64 65 66
## Contribuer au code

### Installer sa copie de l'OPAC

67
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:
Laurent's avatar
Laurent committed
68 69 70 71 72 73 74
```bash
cd /var/www
git clone git@git.afi-sa.fr:mon_compte/opacce.git
```

### Faire des modifications et les pousser vers gitlab

Laurent's avatar
Laurent committed
75
Une fois quelques modifications effectuées, l'envoi des données se fait en deux temps.
Laurent's avatar
Laurent committed
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96

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

Laurent's avatar
Laurent committed
97
Tout d'abord, il faut déclarer le dépôt de la version officielle (upstream) dans votre projet local:
Laurent's avatar
Laurent committed
98 99 100 101 102 103 104 105 106 107 108 109 110 111
```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
```
Laurent's avatar
Laurent committed
112 113 114 115 116 117



## Créer un nouveau skin

### Création
Laurent's avatar
Laurent committed
118 119 120

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

Laurent's avatar
Laurent committed
121
```bash
Laurent's avatar
Laurent committed
122 123
cd skins
cp -a ../public/opac/skins/modele mon_skin
Laurent's avatar
Laurent committed
124
```
Laurent's avatar
Laurent committed
125 126 127 128 129

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



Laurent's avatar
Laurent committed
130
### Sauvegarde sur GitLab
Laurent's avatar
Laurent committed
131

Laurent's avatar
Laurent committed
132
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.
Laurent's avatar
Laurent committed
133 134 135

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

Laurent's avatar
Laurent committed
136
```bash
Laurent's avatar
Laurent committed
137 138 139 140 141 142
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
Laurent's avatar
Laurent committed
143
```
Laurent's avatar
Laurent committed
144 145 146 147

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


Laurent's avatar
Laurent committed
148 149 150
### Description des répertoires

* **css/** contient le fichier global.css sur lequel travailler. Les autres fichiers sont destinés à devenir obsolètes.
Laurent's avatar
Laurent committed
151
* **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.
Laurent's avatar
Laurent committed
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
* **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
174
* **skin_head.phtml** pour rajouter des éléments dans la balise **head** du site
Laurent's avatar
Laurent committed
175
* **accueil.phtml** pour la page d'accueil
Laurent's avatar
Laurent committed
176
* **contenu.phtml** pour les autres pages