PHPIndex

# Premier pas

## Configurer son environnement (Docker)

FreshRSS est construit en PHP et utilise le framework Minz. Les
dépendancessont directement incluses dans le code source, donc vous n’avez
pas besoin d’utiliser Composer.

Il existe plusieurs façons de configurer votre environnement
dedéveloppement. La méthode la plus simple et la plus supportée est basée
surDocker. C’est la solution qui est documentée ci-dessous. Si vous avez
déjà unenvironnement PHP fonctionnel, vous n’en avez probablement pas
besoin.

Nous supposons ici que vous utilisez une distribution GNU/Linux, capable
d’exécuter Docker. Sinon, vous devrez adapter les commandes en conséquence.

Les commandes qui suivent doivent être exécutées dans une console. Ils
commencent par `$` quand les commandes doivent être exécutées en tant
qu’utilisateur normal, et par `#` quand elles doivent être exécutées en tant
qu’utilisateur root. Vous n’avez pas besoin de taper ces caractères. Un
chemin d’accès peut être indiqué devant ces caractères pour vous aider à
identifier où ils doivent être exécutés. Par exemple, `app$ echo 'Hello
World'` indique que vous devez exécuter la commande `echo` dans le
répertoire `app/`.

Tout d’abord, vous devez installer
[Docker](https://docs.docker.com/install/linux/docker-ce/ubuntu/).

Une fois que c’est fait, clonez le dépôt de code de la manière suivante :

```sh
git clone https://github.com/FreshRSS/FreshRSS.git
cd FreshRSS
```

Notez que, pour contribuer, vous devrez d’abord « forker » ce dépôt de code
(ou dépôt de code référent) et cloner votre « fork » à la place de ce
dépôt. Adaptez les commandes en conséquence.

Ensuite, la seule commande que vous devez connaître est la suivante :

```sh
make start
```

Cela peut prendre un certain temps pour que Docker télécharge l’image
utilisée. Dans le cas où la commande échoue pour un problème de droit, il
faudra soit ajouter votre utilisateur au groupe `docker`, soit relancer la
commande en la préfixant par `sudo`.

**Vous pouvez maintenant accéder à FreshRSS à [http://localhost:8080](http://localhost:8080).** Suivez simplement le processus d’installation et sélectionnez la base de données SQLite.

Vous pouvez arrêter les conteneurs en tapant <kbd>Control</kbd> + <kbd>c</kbd> ou avec la commande suivante, dans un autre terminal:

```sh
make stop
```

Si la configuration vous intéresse, les commandes `make` sont définies dans
le fichier [`Makefile`](/Makefile).

Si vous avez besoin d’utiliser une image Docker identifiée par un tag
différent (par défaut `alpine`), vous pouvez surcharger de la manière
suivante la variable d’environnement `TAG` au moment de l’exécution de la
commande :

```sh
TAG=alpine make start
```

Vous pouvez trouver la liste complète des tags disponibles [sur le hub
Docker](https://hub.docker.com/r/freshrss/freshrss/tags).

Si vous voulez construire l’image Docker, vous pouvez lancer la commande
suivante :

```sh
make build
```

La valeur de la variable `TAG` peut contenir n’importe quelle valeur (par
exemple `local`). Vous pouvez cibler une architecture spécifique en ajoutant
`-alpine` à la fin du tag (par exemple `local-alpine`).

## Architecture du projet

> **À FAIRE**

## Extensions

Si vous souhaitez créer votre propre extension FreshRSS, consultez la
[documentation de l’extension](03_Backend/05_Extensions.md).

## Style de codage

Si vous désirez contribuer au code, il est important de respecter le style
de codage suivant. Le code actuel ne le respecte pas entièrement mais il est
de notre devoir à tous de le changer dès que l’occasion se présente.

Aucune nouvelle contribution ne respectant pas ces règles ne sera acceptée
tant que les corrections nécessaires ne sont pas appliquées.

### Espaces, tabulations et autres caractères blancs

#### Indentation

L’indentation du code doit être faite impérativement avec des tabulations.

#### Alignement

Une fois l’indentation faite, il peut être nécessaire de faire un alignement
pour simplifier la lecture. Dans ce cas, il faut utiliser les espaces.

```php
$resultat = une_fonction_avec_un_nom_long($param1, $param2,
                                          $param3, $param4);
```

#### Fin de ligne

Le caractère de fin de ligne doit être un saut de ligne (LF) qui est le
caractère de fin de ligne des systèmes *NIX. Ce caractère ne doit pas être
précédé par des caractères blanc.

Il est possible de vérifier la présence de caractères blancs en fin de ligne
grâce à Git avec la commande suivante :

```sh
# commande à lancer avant l’ajout des fichiers dans l’index
git diff --check
# commande à lancer après l’ajout des fichiers dans l’index mais avant le commit
git diff --check --cached
```

#### Fin de fichier

Chaque fichier doit se terminer par une ligne vide.

#### Le cas de la virgule, du point et du point-virgule

Il n’y a pas d’espace avant ces caractères, il y en a un après.

#### Le cas des opérateurs

Chaque opérateur est entouré d’espaces.

```php
if ($a == 10) {
	// faire quelque chose
}

echo $a ? 1 : 0;
```

#### Le cas des parenthèses

Il n’y a pas d’espaces entre des parenthèses. Il n’y a pas d’espaces avant
une parenthèse ouvrante sauf si elle est précédée d’un mot-clé. Il n’y a pas
d’espaces après une parenthèse fermante sauf si elle est suivie d’une
accolade ouvrante.

```php
if ($a == 10) {
	// faire quelque chose
}

if ((int)$a == 10) {
	// faire quelque chose
}
```

#### Le cas des fonctions chainées

Ce cas se présente le plus souvent en Javascript. Quand on a des fonctions
chainées, des fonctions anonymes ainsi que des fonctions de rappels, il est
très facile de se perdre. Dans ce cas là, on ajoute une indentation
supplémentaire pour toute l’instruction et on revient au même niveau pour
une instruction de même niveau.

```javascript
// Première instruction
shortcut.add(shortcuts.mark_read, function () {
		//...
	}, {
		'disable_in_input': true
	});
// Deuxième instruction
shortcut.add("shift+" + shortcuts.mark_read, function () {
		//...
	}, {
		'disable_in_input': true
	});
```

### Longueur des lignes

Les lignes ne doivent pas dépasser 80 caractères. Il est cependant autorisé
exceptionnellement de dépasser cette limite s’il n’est pas possible de la
respecter mais en aucun cas, les lignes ne doivent dépasser les 100
caractères.

Dans le cas des fonctions, les paramètres peuvent être déclarés sur
plusieurs lignes.

```php
function ma_fonction($param_1, $param_2,
                     $param_3, $param_4) {
	// faire quelque chose
}
```

### Nommage

L’ensemble des éléments du code (fonctions, classes, méthodes et variables)
doivent être nommés de manière à décrire leur usage de façon concise.

#### Fonctions et variables

Les fonctions et les variables doivent suivre la convention "snake case".

```php
// une fontion
function nom_de_la_fontion() {
	// faire quelque chose
}
// une variable
$nom_de_la_variable;
```

#### Méthodes

Les méthodes doivent suivre la convention "lower camel case".

```php
private function nomDeLaMethode() {
	// faire quelque chose
}
```

#### Classes

Les classes doivent suivre la convention "upper camel case".

```php
abstract class NomDeLaClasse {}
```

### Encodage

Les fichiers doivent être encodés en UTF-8.

### Compatibilité PHP

Assurez-vous que votre code fonctionne avec une version de PHP aussi
ancienne que celle que FreshRSS supporte officiellement.

### Divers

#### Le cas des opérateurs sur plusieurs lignes

Les opérateurs doivent être en fin de ligne dans le cas de conditions sur
plusieurs lignes.

```php
if ($a == 10 ||
    $a == 20) {
	// faire quelque chose
}
```

#### Fin de fichier PHP

Si le fichier ne contient que du PHP, il ne doit pas comporter de balise
fermante.

#### Tableaux

Lors de l’écriture de tableaux sur plusieurs lignes, tous les éléments
doivent être suivis d’une virgule (même le dernier).

```php
$variable = [
	"valeur 1",
	"valeur 2",
	"valeur 3",
];
```

# Remonter un problème ou une suggestion

Malgré le soin apporté à FreshRSS, il se peut que des bugs apparaissent
encore. Le projet est jeune et le développement dynamique, aussi celui-ci
pourra être corrigé rapidement. Il se peut aussi que vous ayez en tête une
fonctionnalité qui n’existe pas encore. Que celle-ci vous paraisse idiote,
farfelue, inutile ou trop spécifique, il ne faut surtout pas hésiter à nous
la proposer ! Très souvent des « idées en l’air » ont trouvé une oreille
attentive. Ce sont les regards externes qui font le plus évoluer le projet.

Si vous êtes convaincus qu’il faut vous faire entendre, voici la marche à
suivre.

## Sur GitHub

GitHub est la plate-forme à privilégier pour vos demandes. En effet, cela
nous permet de pouvoir discuter à plusieurs sur un problème ou une
suggestion et de faire émerger, souvent, des idées nouvelles. Ne négligeons
pas cet aspect « social » !

1. [Rendez-vous sur le gestionnaire de tickets de
	bugs](https://github.com/FreshRSS/FreshRSS/issues)
2. Commencez par rechercher si une demande similaire n’a pas déjà été
	faite. Si oui, n’hésitez pas à ajouter votre voix à la demande.
3. Si votre demande est nouvelle, [ouvrez un nouveau ticket de
	bug](https://github.com/FreshRSS/FreshRSS/issues/new)
4. Rédigez enfin votre demande. Si vous maitrisez l’anglais, c’est la
	langue à privilégier car cela permet d’ouvrir la discussion à un plus
	grand nombre de personnes. Sinon, ce n’est pas grave, continuez en
	français :)
5. Merci de bien vouloir suivre les quelques conseils donnés plus bas pour
	faciliter la prise en compte de votre ticket.

## De façon informelle

Tout le monde n’aime pas ou n’utilise pas GitHub pour des raisons aussi
diverses que légitimes. C’est pourquoi vous pouvez aussi nous contacter de
façon plus informelle.

* Sur [notre chat
	Mattermost](https://framateam.org/signup_user_complete/?id=e2680d3e3128b9fac8fdb3003b0024ee)
* Sur [les listes de
	diffusion](https://freshrss.org/announce-of-the-mailing-lists.html)
* À des évènements / rencontres autour du Logiciel Libre
* Autour d’une bière dans un bar
* Etc.

## Conseils

Voici quelques conseils pour bien présenter votre remontée de bug ou votre
suggestion :


* **Faites attention à l’orthographe.** même si ce n’est pas toujours
	facile, faites votre maximum. ;)
* **Donnez un titre explicite à votre demande**, quitte à ce qu’il soit un
	peu long. Cela nous aide non seulement à comprendre votre demande, mais
	aussi à retrouver votre ticket plus tard.
* **Une demande = un ticket.** Vous pouvez avoir des tas d’idées mais vous
	avez peur de spammer le gestionnaire de bugs : ça ne fait rien. Il vaut
	mieux avoir un peu trop de tickets que trop de demandes dans un seul. On
	s’occupera de fermer et regrouper les demandes qui le peuvent.
* Si vous remontez un bug, pensez à nous **fournir les logs de FreshRSS**
	(accessibles dans les dossier `data/log/` de FreshRSS) **et PHP**
	(l’emplacement peut varier selon les distributions, mais pensez à chercher
	dans `/var/log/httpd` ou `/var/log/apache`).
* Si vous ne trouvez pas les fichiers de logs, précisez-le dans votre ticket
	afin que nous sachions que vous avez déjà cherché.
* Tous les bugs ne nécessitent pas les logs, mais si vous doutez, mieux vaut
	nous les fournir. Les logs sont importants et très utiles pour débugguer !
* Il se peut que les logs puissent révéler des informations plus ou moins
	confidentielles, **faites attention à ne rien divulguer de sensible.**

De plus, face à un bug, je ne peux que vous encourager à suivre le format de
message suivant (tiré du [site de Sam &
Max](http://sametmax.com/template-de-demande-daide-en-informatique/)) :

### Quel est mon objectif ?

Donnez le contexte général de ce que vous essayiez de faire.

### Qu’est-ce que j’ai essayé de faire ?

Expliquez pas à pas ce que vous avez fait afin que nous puissions reproduire
le bug.

### Quels résultats ai-je obtenus ?

Le bug : ce que vous voyez qui n’aurez pas dû se passer. Ici vous pouvez
fournir les logs.

### Quel était le résultat attendu ?

Afin que nous comprenions bien où est le problème… au moins selon vous :p

### Quelle est ma situation ?

Pensez à donner les informations suivantes si vous les connaissez :

1. Quel navigateur ? Quelle version ?
2. Quel serveur : Apache, Nginx ? Quelle version ?
3. Quelle version de PHP ?
4. Quelle base de données : SQLite, MySQL, MariaDB, PostgreSQL ? Quelle version ?
5. Quelle distribution sur le serveur ? Et… quelle version ?

## Système de branches

### Élémentaire

Si vous êtes novice dans Git, voici quelques ressources qui pourraient vous
être utiles :

* [Article du blog de GitHub](https://github.com/blog/120-new-to-git)
* <http://try.github.com/>
* <http://sixrevisions.com/resources/git-tutorials-beginners/>
* <http://rogerdudler.github.io/git-guide/>

### Obtenir le dernier code du répertoire FreshRSS

Vous devez avant tout ajouter le repo officiel à votre liste de repo remote
:

```sh
git remote add upstream git@github.com:FreshRSS/FreshRSS.git
```

Vous pouvez vérifier que le repo remote a été ajouté avec succès en
utilisant :

```sh
git remote -v show
```

Vous pouvez maintenant pull le dernier code de développement :

```sh
git checkout edge
git pull upstream edge
```

### Lancer une nouvelle branche de développement

```sh
git checkout -b mon-branch-developpement
```

## Proposer un patch

```sh
# Ajoutez le fichier modifié, ici actualize_script.php
git add app/actualize_script.php
# Commitez le changement et écrivez un message de commit approprié.
git commit
# Vérifiez deux fois que tout a l’air d’aller bien
git show
# Poussez les changements sur ton fork
git push
```

Vous pouvez maintenant créer une PR en fonction de votre branche.

### Comment écrire un message de commit

Un message de commit devrait décrire succinctement les changements sur la
première ligne. Par exemple :

> Fixe une icône cassée

Si nécessaire, une ligne blanche et une explication plus longue peuvent le
suivre.

Pour d’autres conseils, voir
[ici](https://chris.beams.io/posts/git-commit/).

# Running tests

FreshRSS is tested with [PHPUnit](https://phpunit.de/). No code should be
merged in `edge` if the tests don’t pass.

## Locally

As a developer, you can run the test suite on your PC easily with `make`
commands. You can run the test suite with:

```sh
make test
```

This command downloads the PHPUnit binary and verifies its checksum. If the
verification fails, the file is deleted. In this case, you should [open an
issue on GitHub](https://github.com/FreshRSS/FreshRSS/issues/new) to let
maintainers know about the problem.

Then, it executes PHPUnit in a Docker container. If you don’t use Docker,
you can run the command directly with:

```sh
NO_DOCKER=true make test
```

## Intégration continue avec GitHub Actions

Les tests sont lancés automatiquement dès que vous ouvrez une « pull request » sur GitHub.
Ceux-ci sont lancés grace aux « [GitHub Actions](https://github.com/FreshRSS/FreshRSS/actions) ».
Cette action est nécessaire pour s’assurer qu’aucune régression ne soit introduite dans le code. Nous n’accepterons aucune PR si les tests ne sont pas valides, nous vous demanderons donc de corriger tout ce qui doit l’être avant de commencer à relire votre code.

Si cela vous intéresse, vous pouvez étudier [le fichier de configuration](https://github.com/FreshRSS/FreshRSS/blob/edge/.github/workflows/tests.yml).

# Préparer la sortie

Afin d’avoir le plus de retour possible avant une sortie, il est préférable
de l’annoncer sur GitHub en créant un ticket dédié ([voir les
exemples](https://github.com/FreshRSS/FreshRSS/search?utf8=%E2%9C%93&q=Call+for+testing&type=Issues)).
Ceci est à faire **au moins une semaine à l’avance**.

Il est aussi recommandé de faire l’annonce sur <mailing@freshrss.org>.

## S’assurer de l’état de dev

Avant de sortir une nouvelle version de FreshRSS, il faut vous assurer que
le code est stable et ne présente pas de bugs majeurs. Idéalement, il
faudrait que nos tests soient automatisés et exécutés avant toute
publication.

Il faut aussi **vous assurer que le fichier CHANGELOG est à jour** avec les
mises à jour de la version à sortir.

## Processus Git

```console
$ git checkout edge
$ git pull
$ vim constants.php
# Mettre à jour le numéro de version x.y.z de FRESHRSS_VERSION
$ git commit -a
Version x.y.z
$ git tag -a x.y.z
Version x.y.z
$ git push && git push --tags
```

## Mise à jour de update.freshrss.org

Il est important de mettre à jour update.freshrss.org puisqu’il s’agit du
service par défaut gérant les mises à jour automatiques de FreshRSS.

Le dépot gérant le code se trouve sur GitHub :
[FreshRSS/update.freshrss.org](https://github.com/FreshRSS/update.freshrss.org/).

### Écriture du script de mise à jour

Les scripts se trouvent dans le répertoire `./scripts/` et doivent être de
la forme `update_to_x.y.z.php`. On trouve aussi dans ce répertoire
`update_to_dev.php` destiné aux mises à jour de la branche `edge` (ce
script ne doit pas inclure de code spécifique à une version particulière !)
et `update_util.php` contenant une liste de fonctions utiles à tous les
scripts.

Afin d’écrire un nouveau script, il est préférable de copier / coller celui
de la dernière version ou de partir de `update_to_dev.php`. La première
chose à faire est de définir l’URL à partir de laquelle sera téléchargée le
package FreshRSS (`PACKAGE_URL`). L’URL est de la forme
`https://codeload.github.com/FreshRSS/FreshRSS/zip/x.y.z`.

Il existe ensuite 5 fonctions à remplir :

* `apply_update()` qui se charge de sauvegarder le répertoire contenant les
	données, de vérifier sa structure, de télécharger le package FreshRSS, de
	le déployer et de tout nettoyer. Cette fonction est pré-remplie mais des
	ajustements peuvent être faits si besoin est (ex. réorganisation de la
	structure de `./data`). Elle retourne `true` si aucun problème n’est
	survenu ou une chaîne de caractères indiquant un soucis ;
* `need_info_update()` retourne `true` si l’utilisateur doit intervenir
	durant la mise à jour ou `false` sinon ;
* `ask_info_update()` affiche un formulaire à l’utilisateur si
	`need_info_update()` a retourné `true` ;
* `save_info_update()` est chargée de sauvegarder les informations
	renseignées par l’utilisateur (issues du formulaire de
	`ask_info_update()`) ;
* `do_post_update()` est exécutée à la fin de la mise à jour et prend en
	compte le code de la nouvelle version (ex. si la nouvelle version modifie
	l’objet `Minz_Configuration`, vous bénéficierez de ces améliorations).

## Mise à jour du fichier de versions

Lorsque le script a été écrit et versionné, il est nécessaire de mettre à
jour le fichier `./versions.php` qui contient une table de correspondances
indiquant quelles versions sont mises à jour vers quelles autres versions.

Voici un exemple de fichier `versions.php` :

```php
<?php
return array(
	// STABLE
	'0.8.0' => '1.0.0',
	'0.8.1' => '1.0.0',
	'1.0.0' => '1.0.1',  // doesn’t exist (yet)
	// DEV
	'1.1.2-dev' => 'dev',
	'1.1.3-dev' => 'dev',
	'1.1.4-dev' => 'dev',
);
```

Et voici comment fonctionne cette table :

* à gauche se trouve la version N, à droite la version N+1 ;
* les versions `x.y.z-dev` sont **toutes** mises à jour vers `edge` ;
* les versions stables sont mises à jour vers des versions stables ;
* il est possible de sauter plusieurs versions d’un coup à condition que les
	scripts de mise à jour le prennent en charge ;
* il est conseillé d’indiquer la correspondance de la version courante vers
	sa potentielle future version en précisant que cette version n’existe pas
	encore. Tant que le script correspondant n’existera pas, rien ne se
	passera.

Il est **très fortement** indiqué de garder ce fichier rangé selon les
numéros de versions en séparant les versions stables et de dev.

## Déploiement

Avant de mettre à jour update.freshrss.org, il est préférable de tester avec
dev.update.freshrss.org qui correspond à la pré-production. Mettez donc à
jour dev.update.freshrss.org et changez l’URL `FRESHRSS_UPDATE_WEBSITE` de
votre instance FreshRSS. Lancez la mise à jour et vérifiez que celle-ci se
déroule correctement.

Lorsque vous serez satisfait, mettez à jour update.freshrss.org avec le
nouveau script et en testant de nouveau puis passez à la suite.

## Mise à jour des services FreshRSS

Deux services sont à mettre à jour immédiatement après la mise à jour de
update.freshrss.org :

* rss.freshrss.org ;
* demo.freshrss.org (identifiants publics : `demo` / `demodemo`).

## Annoncer publiquement la sortie

Lorsque tout fonctionne, il est temps d’annoncer la sortie au monde entier !

* sur GitHub en créant [une nouvelle
	release](https://github.com/FreshRSS/FreshRSS/releases/new) ;
* sur le blog de freshrss.org au minimum pour les versions stables (écrire
	l’article sur
	[FreshRSS/freshrss.org](https://github.com/FreshRSS/freshrss.org)).
* sur Twitter (compte [@FreshRSS](https://twitter.com/FreshRSS)) ;
* et sur <mailing@freshrss.org> ;

## Lancer la prochaine version de développement

```console
$ git checkout edge
$ vim constants.php
# Mettre à jour le numéro de version de FRESHRSS_VERSION
$ vim CHANGELOG.md
# Préparer la section pour la prochaine version
$ git add CHANGELOG.md && git commit && git push
```

Pensez aussi à mettre à jour update.freshrss.org pour qu’il prenne en compte
la version de développement actuelle.