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

1. Gestionnaire de dépendances (Composer)
2. Gestionnaire de versions (Git)
3. Structure d'une bibliothèque
4. Rush Release
   1. Élaboration et maturation
   2. Cycle de release
   3. Versions de PHP

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 :

1. l'état beta représente une bibliothèque en cours d'élaboration, d'écriture, de développement ;
2. 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 ;
3. 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.20.02.24.

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.