Forge · git.felinn.org
git.felinn.org est le service de gestion de projet et de versionnage de la FELINN, basé sur le logiciel libre Gitlab Community Edition. Il permet de collaborer sur des projets textuels (code, documentation, scénarios...) avec des outils de gestion et de versionnages avancés.
Les screenshots présents dans cette documentation ont été réalisés avec le thème sombre de Gitlab. Si vous souhaitez l'utiliser vous aussi, rendez-vous dans vos préférences, sélectionner Dark Mode dans Navigation theme et Dark dans Syntax highlighting theme, puis sauvegarder en cliquant sur Save changes en bas de la page.
Faire des retours sur les services de la FELINN
L'instance Gitlab permet notamment aux utilisateurices de faire des retours et d'échanger avec la FELINN sur les différents services proposés : problèmes rencontrés, bugs, idées d'amélioration etc.
Se connecter
Cliquer sur le bouton Sign-in en haut à droite de l'accueil de Gitlab. La page d'authentification centralisée Hiboo des services FELINN devrait alors s'afficher. Renseigner son nom d'utilisateurice et son mot de passe FELINN dans les champs correspondants. Enfin, cliquer sur Se connecter.
Trouver le bon projet pour publier un retour
Gitlab est principalement organisé en projets, chaque projet permettant d'organiser la maintenance et le développement d'un service FELINN, ou d'une autre création de l'association ou de ses membres. Dans le groupe FELINN Core, un projet correspond à un service FELINN actuellement déployé : il peut contenir des fichiers de configuration, du code, des médias et de la documentation qui permettent de le faire fonctionner (tout cela versionné grâce protocole git), mais aussi un gestionnaire de tickets nommés issues, permettant aux développeur·euses d'améliorer les services et aux utilisateurices de faire des retours sur leur expérience.
Pour trouver le projet désiré, par exemple Matrix, vous pouvez cliquer sur le bouton Projet en haut à gauche de l'interface, taper le nom du projet dans la barre de rechercher et cliquer sur le résultat proposé :
Accéder aux issues et en créer
Une issue peut correspondre à un bug, un problème rencontré ou une idée d'amélioration concernant le projet sélectionné. Une fois sur la page d'un projet (exemple : la page de matrix) vous pouvez accéder à la liste des issues en cours en cliquant sur Issues dans le grand menu du panneau de gauche :
.
Vous accéderez alors à la liste des issues ouvertes (à traiter ou en cours de traitement) :
Vous pouvez également accéder aux issues du projet déjà traitées en cliquant sur Closed ou à toutes les issues en cliquant sur All :
Les labels colorés permettent de les classer en différentes catégories et état d'avancement. Ces labels sont gérés par les développeurs et développeuses de la FELINN. Vous n'avez donc pas à vous en soucier pour la création de votre issue.
Afin d'éviter les doublons avant d'ouvrir une nouvelle issue, il est conseillé de regarder dans la liste des issues ouvertes s'il y en a pas déjà une déjà existante correspondant à votre demande, ou bien une issue déjà fermée (et donc résolue).
Créer une issue
Cliquer sur le lien New Issue dans la catégorie This Project du menu d'ajout, accessible en cliquant sur l'icône + du menu du haut :
.
L'interface de création d'issue vous permettra alors de renseigner les informations appropriées :
- Title : Nom de l'issue, résumant en quelques mots ce qu'il en retourne.
- Description : Description détaillée. Ne pas hésiter à rentrer dans les détails, poster des liens et captures d'écran/vidéo illustrant le propos.
- Submit issue : Créer l'issue
Les issues et commentaires s'écrivent simplement dans le langage Markdown (ressources plus avancées et en anglais), mais les boutons à droite de l'éditeur de texte permettent de formater et joindre des fichiers facilement :
Les images et autres fichiers peuvent être joint en les glissant-déposant directement dans la zone de texte !
Pour prévisualiser son issue, bien formatée et intégrant les médias, vous pouvez cliquer sur Preview, en haut du champ description :
Gestion de l'issue et commentaires
Une fois l'issue ouverte, les personnes impliquées dans le projet seront notifiées et pourront vous répondre en commentaire de l'issue pour demander des éclaircissements, donner leurs avis, discuter… Si l'issue est pertinente, elle sera traitée dans des délais variant selon sa priorité et la disponibilité de celleux qui travaillent sur le projet FELINN concerné. Les gestionnaires du projet ajouteront aussi des labels à votre issue pour bien la classer, et se réservent le droit de l'éditer pour améliorer sa lisibilité ou ajouter des informations supplémentaires.
Vous pouvez aussi commenter votre issue, ou d'autres issues, grâce au formulaire de bas de page. C'est un éditeur markdown semblable à celui de la création d'issue :
Vous recevrez des notifications par mail lorsque des membres postent des commentaires sous votre issue, ou lorsque qu'on s'adresse à vous dans une issue ou un commentaire. Aussi, le bouton To-Do List dans le menu du haut vous permet de visualiser les dernières activités vous concernant dans Gitlab :
Tips
- Il est possible de répondre directement à un commentaire en appuyant sur l'icône de bulle à droite du commentaire, ou d'ajouter une réaction smiley en appuyant sur l'icône de tête qui sourit.
- Vous pouvez interpeller des utilisateurices du Gitlab dans une issue ou dans un commentaire en tapant un
@, puis en commençant à taper son pseudo. - Créer facilement des liens vers d'autres issues en tapant un
#suivi du numéro d'issue - Ajouter des smileys en tapant
:puis en tapant le nom du smiley à insérer (exemple:fire:s'affichera 🔥) - La vue
Boards, accessible en cliquant sur le bouton correspondant du menuIssuesdu panneau de gauche, permet d'afficher une vue des issues de type kanban, avec les issues ouvertes dans la colonne de gauche et les issues fermées dans la colonne de droite. - N'hésitez pas à explorer vos paramètres de notifications de votre profil Gitlab pour régler finement quelles actions déclencheront l'envoi de mails.
Aller plus loin
Projets Gitlab des utilisateurices
Une fois connecté·e à Gitlab, il est possible de créer des projets personnels grâce au bouton New project. Vous pouvez alors choisir entre un projet vide, ou l'utilisation d'un template pour bien commencer votre projet, ou encore l'import d'un projet provenant d'une autre forge (un autre Gitlab, Github, Bit bucket...).
Ensuite vous devrez choisir le niveau de visibilité du projet : public (le monde entier y a accès), internal (uniquement les utilisateurices connecté·es peuvent y accéder), private (vous êtes les seul·es à y avoir accès). Vous pouvez aussi cocher la case permettant d'ajouter un fichier README.md à votre projet, celui-ci permettant d'afficher une description du projet dans Gitlab.
Pour certains projets il est possible d'ouvrir une issue en envoyant un email. Pour cela il faut activer le Service Desk dans les paramètres du projet. Une fois activée, l'adresse email de référence est visible dans les paramètres et dans la liste des issues.
Le Web Editor et le Web IDE intégrés à Gitlab permettent de créer et éditer les fichiers de votre projet depuis l'interface web. Néanmoins, pour les projets conséquents ou impliquant plusieurs utilisateurices, il est préférable de s'intéresser à l'utilisation de Git et à l'édition des fichiers en local.
Utilisation de Git
Gitlab repose sur le logiciel libre de gestion de versions décentralisé Git. Extrêmement populaire dans le monde du développement informatique, Git permet de gérer le versionnage de tous les fichiers d'un projet et donc de visualiser l'historique de leurs modifications, mais aussi de collaborer de manière efficace, avec des outils de comparaison de fichiers, de gestion de conflits et le développement par branches. Idéal pour la programmation, il est aussi beaucoup utilisé pour tout type de projet textuels (écriture de scénarios, textes de loi, documentations, recherche...).
La pluparts des logiciels libres utilisent Git ou un logiciel semblable pour gérer le code source et permettre à touste de participer au développement. Le côté décentralisé de Git permet justement à n'importe qui de « cloner » un projet, y apporter des modifications et proposer celles-ci à la communauté. Cependant, Git étant un outil de bas niveau, principalement utilisable avec un terminal ou une interface graphique sommaire, les logiciels de forge tels que Gitlab ou Github permettent aux communautés de s'organiser autour des projets grâce à des applications web avancées.
Si l'utilisation de Git vous intéresse, nous vous invitons à consulter la documentation officielle de Git (EN) ou à lire le livre Git Wikibooks (FR) qui permet d'apprendre rapidement les bases de Git.
Configurer Git pour travailler sur des projets du Gitlab FELINN
Il est nécessaire de configurer correctement Git pour l'utilisation avec notre Gitlab. Deux méthodes d'authentification sont disponibles : HTTPS et SSH. La procédure à suivre est expliquée dans la documentation officielle de Gitlab.
Avec SSH, le port à utiliser est le 1222
Pour cloner un projet en spécifiant ce port, vous pouvez modifier la syntaxe de l'adresse utilisée pour le clonage : git clone git@git.felinn.org:user/project.git devient git clone ssh://git@git.felinn.org:1222/user/project.git
Pour spécifier le port SSH utilisé par tout les dépots du Gitlab FELINN de votre machine, modifiez votre fichier ~/.ssh/config (le créer si besoin) et ajoutez-y les lignes suivantes :
Host git.felinn.org
Port 1222
Contribuer aux projets de la FELINN
Si vous êtes intéressé·es pour contributer à un projet de l'association dont les contributions principales se font sur Gitlab, contactez le conseil sur le salon Membres de matrix.felinn.org, vous aurez alors l'accès au salon Dev de matrix.felinn.org, et vous serez promu·e administrateurice sur Gitlab. La décision doit être prise au niveau CC-CV.
N'hésitez pas à vous familiariser avec notre fonctionnement admin de Gitlab !