CONTRIB.en.md

# Contribute to source code

## Content
* [Prerequisite](#Prerequisite)
* [Create your own copy of the project](#Create-your-own-copy-of-the-project)
* [How to contribute to the source code](#How-to-contribute-to-the source-code)
* [Create a new skin](#Create-a-new-skin)

## Prerequisite

AFI & BIBLIBRE developpment teams use the opensource [forge](https://fr.wikipedia.org/wiki/Forge_%28informatique%29) libre [GitLab](https://www.gitlab.com) and the[SCM](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).

Source code are hosted on https://git.afi-sa.fr. Public projects are accessible here https://git.afi-sa.fr/public.


## Create your own copy of the project

### Create a gitlab account

From the [Sign Up](http://git.afi-sa.fr/users/sign_up) page, you can create your account.  You will receive a confirmation email. 


### Clone the project

Once connected, from the [OPACCE project page](http://git.afi-sa.fr/afi/opacce), clic on the **Fork repository** button. You can also clone the project  [here](http://git.afi-sa.fr/afi/opacce/fork).

This will create your own public copy of the project accessible through http://git.afi-sa.fr/my-account/opacce.


The SSH access is given from your project home page. for example git@git.afi-sa.fr:my_account/opacce.git


### Installing SSH access

In order to upload modifications on the gitlab you need SSH access.  On  [Your account page](http://git.afi-sa.fr/profile), in the [SSH Keys](http://git.afi-sa.fr/profile/keys) tab, use the link [Add SSH Key](http://git.afi-sa.fr/profile/keys/new).

#### Create & register your key

If you already have a key on your workstation in  **~/.ssh/id_rsa.pub**, copy it.

otherwise, [ generate a key ](http://git.afi-sa.fr/help/ssh), with the following command:
```bash
ssh-keygen -t rsa -C "addresse_email@domaine.ext"
```

to show the content:
```bash
cat ~/.ssh/id_rsa.pub
```

#### configure SSH access

SS access uses  **2950** port. Create or modify the **~/.ssh/config** file to add the following lines:
```
Host git.afi-sa.fr
  Hostname git.afi-sa.fr
  Port 2950
  User git
  IdentityFile ~/.ssh/id_rsa

```

## How to contribute to the source code

### Install your own copy of the project

The install process is described [Installation instructions](INSTALL.en.md), unlike described in the [Downloading source code](INSTALL.en.md#Downloading-source-code) section, you should use your own depository:
```bash
cd /var/www
git clone git@git.afi-sa.fr:mon_compte/opacce.git
```

### Update files and push them to  gitlab

Once  your done with your udpates, the file upload is done in two steps.

1. Commit your modifications locally
```bash
git commit -a -m "Commentaires des modifications"
```

2. Push your master branch to gitlab (origin):
```bash
git push origin master
```

For more details please check [Pro Git](http://git-scm.com/book/fr)


### Propose patches to the release team

On your private GitLab page, **Merge Requests** tab, clic on the link **+ New Merge Request** and fill the form to describe your patch. 


### retrieve the last official release

Declate the official version depository (upstream) in your local project:
```bash
git remote add upstream git@git.afi-sa.fr:afi/opacce.git
```

Merge modifications:

```bash
# Download all modification from the master project
git fetch upstream master
# Merge the modifications in your local project
git merge upstream/master
# Push the result on the depository
git push origin master
```



## Create a new skin

### Create

Go to the skin directory in the root folder and duplicate it

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

Go the the profil config page in the opac back office, you should see your skin in the combo.


### Save you skin on GitLab

Create a project on [GitLab](https://git.afi-sa.fr) to store the sourcecode. For exemple https://git.afi-sa.fr/mon_compte/mon_skin.

Go to my_skin and initialise the depository:

```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
```

Now, new files should be acessible from  https://git.afi-sa.fr/mon_compte/mon_skin/files


### Folder description

* **css/** contains the global.css file where to work. Other files are deprecated.
* **images/** icons **images/support/** for doc types. Files must be named: **support_id_.png**, for exemple **support_1.png** for books.
* **templates/** Box template on the home page. Files must be named with **_**, the liste will appear in the combo **Box style**. Every template can include 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>
```


All files can be renamed in **application/modules/opac/views/scripts** . main files are:
* **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