Sources
Hoa distribue les projets principaux suivants :
Central
: l'ensemble de toutes les bibliothèques standards ;Library/*
: bibliothèques standards isolées ;Hoathis/*
: bibliothèques utilisateurs isolées (maintenues par Hoa).
Il existe plusieurs façon d'installer Hoa : dans sa
totalité (avec le central) ou en partie
(choix des bibliothèques), et globalement (sur le système)
ou localement (dans une application). Dans le cas d'une
installation globale et pour les systèmes respectants le
Filesystem
Hierarchy Standard (dans sa version 2.2 minimum), Hoa préfèrera
s'installer dans le dossier /usr/local/lib/Hoa/
. Pour les
autres systèmes, comme par exemple Windows, Hoa préfèrera s'installer dans
le dossier C:\Program Files\Hoa\
.
Table des matières
- Gestionnaire de dépendances (Composer)
- Gestionnaire de versions (Git)
- Structure d'une bibliothèque
- Rush Release
Gestionnaire de dépendances (Composer)
Pour gérer les dépendances entre les bibliothèques de Hoa, nous
recommandons l'outil Composer. Toutes
les dépendances gérées avec Composer sont enregistrées auprès du dépôt
Packagist sous les noms
hoa/library
et hoathis/library
.
Ainsi, par exemple, pour installer la bibliothèque
Hoa\Websocket
, il faudra écrire dans un fichier
composer.json
:
{
"require": {
"hoa/websocket": "~3.0"
}
}
Puis pour installer les dépendances :
$ composer install
Il est recommandé de lire la documentation de Composer si vous n'êtes pas familier avec cet outil.
Pour tester que l'installation s'est bien déroulée :
<?php
require_once 'vendor/autoload.php';
var_dump(HOA); // bool(true)
Gestionnaire de versions (Git)
Hoa utilise Git pour tous ses projets.
L'index des dépôts se trouve à l'adresse :
git.hoa-project.net. Les dépôts
sont nommés
project.git
. Ainsi, pour
obtenir les sources du projet Central
:
$ git clone https://git.hoa-project.net/Central.git Hoa.central
Pour obtenir une bibliothèque, par exemple Hoa\Websocket
:
$ git clone https://git.hoa-project.net/Library/Websocket.git Hoa/Websocket
Il est recommandé de lire la documentation de Git si vous n'êtes pas familier avec cet outil.
Si vous souhaitez une installation globale et totale avec le central, tout en respectant la recommandation sur la localisation de Hoa, vous pourrez utiliser un lien symbolique :
$ git clone https://git.hoa-project.net/Central.git /usr/local/lib/Hoa.central
$ ln -s /usr/local/lib/Hoa.central/Hoa /usr/local/lib/Hoa
Des miroirs existent pour la plupart des projets, notamment sur
Github,
Gitlab et
Pikacode. Les noms des
projets sont identiques autant que possible. La plus grosse différence est
pour les bibliothèques : l'accès se fait sans le préfixe
Library/
ou alors Hoathis/
est remplacé par
Hoathis-
. Ainsi :
$ git clone https://github.com/hoaproject/Websocket.git
Les miroirs sont en permanence synchronisés, vous n'aurez jamais de différences.
Pour tester que l'installation s'est bien déroulée :
<?php
require_once '/usr/local/lib/Hoa/Consistency/Prelude.php';
var_dump(HOA); // bool(true)
Structure d'une bibliothèque
Voici la structure d'une bibliothèque :
- sources à la racine ;
Bin/
, pour les binaires ;Documentation/
, pour les chapitres du hack book (documentation) ;Test/
, pour les tests ;README.md
, pour une description en anglais avec des exemples usuels ;composer.json
, pour les dépendances.
Les binaires sont accessibles via la commande : hoa
library:command
. Par exemple, pour
Hoa\Protocol\Bin\Resolve
, nous écrirons :
hoa protocol:resolve
.
Actuellement, les tests sont en cours de migration !
Merci d'être patient.
Rush Release
Hoa utilise un système de release appelé Rush Release, pour Rolling Und ScHeduled Release. Cette section explique ce système, qui, malgré les apparences, est très proche de ce qui est rencontré au quotidien mais répond aux besoins particuliers du projet Hoa.
Élaboration et maturation
Lors de sa vie, une bibliothèque passe dans trois états différents :
- l'état beta représente une bibliothèque en cours d'élaboration, d'écriture, de développement ;
- l'état RC (pour Release Candidate) représente une bibliothèque avec une API fixe, un code abouti et mature ; elle est alors intensivement testée par plusieurs utilisateurs pour éprouver son code et son API ; une fois validée, elle passe dans l'état suivant ;
- l'état finalized représente une bibliothèque finalisée ; son cycle de release peut alors commencer.
Cycle de release
Une fois une bibliothèque finalisée, son cycle de
release peut commencer. Hoa utilise un cycle
appelé
Rolling
Release. Cela signifie que la branche principale,
master
, contient en permanence la dernière
version. Pas besoin d'attendre la sortie d'une nouvelle
version pour avoir les derniers correctifs de sécurité, de performances
ou les dernières nouveautés : la branche principale les propose tout de
suite, sans attente. (Détail : Hoa applique du
part- et true-rolling release).
Toutefois, certains logiciels permettant d'installer Hoa ne comprennent pas cette approche, ou alors elle ne convient pas à tous les environnements de développement ou contextes d'utilisation. C'est pourquoi, Hoa utilise également un autre cycle de release appelé Scheduled-based Release. Les règles sont les suivantes :
- chaque 6 semaines, si au moins un patch a été appliqué dans la branche principale, un nouveau snapshot est créé ;
- avant 6 semaines, si au moins un patch critique ou significatif a été appliqué, un nouveau snapshot est créé.
Les snapshots prennent la forme de
tags dans les dépôts Git. Ils ont le format suivant :
x.YY.mm.dd
, où
x
est le master compatibility
number (détaillé ci-après), YY
est l'année (à
partir de l'année 2000, aussi appelée Rush Epoch),
mm
est le mois et enfin dd
le
jour.
Le master compatibility number (MCN)
représente le nombre de fois où la compatibilité descendante n'a pas pu être
assurée, autrement dit où il n'est pas possible de faire une mise à jour
sans aucun risque (nous parlons aussi de backward
compatibility break, BC break). Avant
qu'une bibliothèque atteigne l'état finalized, son MCN
est défini à 0. Ensuite, il est défini à 1, puis il augmente au besoin. Par
exemple, le snapshot du jour pourrait être
1.21.03.02
.
Ainsi, pour utiliser le dernier snapshot de la
bibliothèque Hoa\Websocket
, il faudra écrire dans votre fichier
composer.json
:
{
"require": {
"hoa/websocket": "~3.0"
}
}
Et pour utiliser la dernière version disponible, il faudra écrire :
{
"require": {
"hoa/websocket": "~3.0@dev"
}
}
L'opérateur
tilde, ou opérateur de la prochaine release
significative, dans Composer équivaut ici à >=3.0,<4.0
,
soit la dernière version possible pour le même MCN.
Versions de PHP
Hoa supporte toutes les versions de PHP supérieures ou égales à la dernière version maintenue par le PHP Group. Nous parlons de lowest required PHP version (LRPV). Même si Hoa est compatible avec des versions plus anciennes, les bibliothèques ne s'y exécuteront volontairement pas. Par conséquent, chaque fois qu'une version de PHP meurt, cela augmente le MCN de chaque bibliothèque.
Il est possible de connaître la LRPV en lisant le
fichier
composer.json
de Hoa\Consistency
.
Actuellement, Hoa supporte toutes les versions supérieures ou égales à
5.5.