- Contribuer au projet
En participant, vous devez respecter le code de conduite du projet.
Beaucoup de choses, l’écriture de code n’étant pas l’unique manière de contribuer au projet !
Il parait que chaque bug relevé sauve un chaton. En tout cas, la technique du ZBSD (Zero-Bug Software Development) semble porter ses fruits, comme le rapporte Andrew Fulton. Donc, si à chaque bug rencontré quelqu’un ouvre une issue avec le label Bug 🐛, ce seront des familles entières de chats qui seront sauvées.
Dans ce cas, ouvrez une nouvelle issue de type Amélioration ❤️ en décrivant bien votre idée.
Si pendant votre participation au projet (que ce soit en l'utilisant ou en participant au code) vous n'avez pas réussit à faire quelque chose par manque de solution, signalez le en ouvrant une issue de type Documentation 📘 .
Et d'ailleurs n'hésitez pas à traiter cette issue en proposant un PR améliorant la documentation si vous avez trouvez une solution !
Il s'agit donc ici d'un projet de backend/API développé en Php sur une base Symfony/Api Platform.
Le projet consistera dans un premier temps à servir le contenu déjà existant du site des CaenCamp.s (pour le moment les contenus sont sous forme de fichiers markdown mis en forme par un Gatsby).
L'enjeu de cette phase sera de servir un contenu sémantiquement valide et standard au travers d'une API Rest Json standard, mais aussi sous forme Json-ld au travers un Api Rest Hydra.
Ensuite, cette API devra intégrer les offres d'emploi et intégrant le travail fait sur le projet jobs-caen-camp.
Puis nous pourrons développer les briques d'un réseau social décentralisé en s'appuyant sur ces contenus et des technologies de type ActivityPub, IndieWeb, Solid...
Quelle que soit votre type d’implication, ce peut-être une bonne chose que d’installer le projet sur votre machine pour pouvoir visualiser votre contribution avant de la proposer sur Github.
Contrairement aux projets précédents des CCC, l'environnement de développement ne s'appuie plus sur Docker.
Cela requière donc l'installation de quelques outils sur votre environnement local. Tout d'abord, vous devez avoir un version de Php 7.4.
Ensuite, il faut avoir les extensions Php demandées par Symfony. Le plus simple pour s'en assurer est d'installer la Cli de Symfony.
Vous gagnerez aussi à installer Composer en global.
Et normalement cela devrait fonctionner.
Note 1: Pour ceux qui préfèrerait utiliser Docker, API-Plateform a très bien documenté l'utilisation d'un environnement complet avec Docker-Compose
Note 2: L'environnement de développement va évoluer, et il faudra sans doute bientôt au minima une base de donnée !
Note 3: N'hésitez pas à documenter la mise ne place de votre environnement sur le Wiki ! Cela permettra de couvrir plusieurs environnement (Linux, Mac, Windows, Docker, ...)
Le projet necessite une base de données PostgreSQL en version 12.
Par default, en local, la base doit être disponible selon la configuration suivante :
// in .env
DATABASE_URL="postgresql://cc_user:[email protected]:5432/cc_db?serverVersion=12&charset=utf8"
Vous pouvez surcharger cette configuration dans votre fichier .env.local.
Si vous n'avez pas/ne voulez pas installer la base de donnée sur votre environnement local, ou si vous avez déjà un PostgreSQL mais dans une version différente, vous pouvez utilisez Docker Compose. Dans ce cas, vous pourrez utiliser les commande make db-start et make db-stop.
Et quelque soit la solution choisie, vous devrez initialiser votre base en jouant les migrations et en important les données existantes (depuis des fichiers markdown de Gatsby) :
make db-initLe projet respecte l'organisation du code d'un projet Symfony.
$ make install$ make startLe code du projet devra respecter le standard de code de Symfony.
Pour cela, nous utilisons le projet PHP Coding Standards Fixer. Ce linter peut être configuré sur de nombreux Ide.s.
Ce n'est pas toujours ce qu'il y a de plus facile à faire sur un projet : écrire une documentation permettant d'utiliser le produit, mais aussi permettant de participer à son élaboration. Et tout aussi difficile, maintenir cette documentation à jours.
Pourtant, et ceci d'expérience, ce sont le plus souvent les projets les mieux documentés qui gagnent l'adhésion de la communauté ! Voici donc les quelques méthodes et règle qui nous avons mis en place aux Coding Caen.Camp.s
Le contrat OpenAPI permet entre autre de générer la documentation en ligne de l'API avec Swagger.
C'est API Plateform qui permet de générer automatiquement la vue swagger, mais il est aussi possible de générer le contrat OpanAPI au format yaml et json. Pour cela, il faut utiliser l'une des recettes du Makefile :
make update_openapi-contractNous utilisons les ADR.s (Architectural Decision Records) pour documenter les prises de décisions liées à l'architecture du projet.
Il existe par exemple un ADR sur la mise en place des ADR.s :)
Vous trouverez plus d'information sur les ADR sur le dépôt coding-caen-camp.
Github fourni un wiki pour chaque dépôt. Autant l'utiliser !
Nous suggérons donc d'utiliser le wiki pour y noter tous les tips, guides, remarques, astuces ... liées au projet.
Afin de faciliter l’intégration (le merge) de vos PR, surtout si elles ajoutent ou modifient du code, celles-ci devront contenir les tests couvrant vos propositions.
Le projet utilise les outils de tests standards de Symfony et ceux décrits dans la documentation d'API Platform.
$ make testLes tests sont lancés sur la plateforme d’intégration continue de Github via les Github actions.
La bonne pratique, c’est de faire des PR, et puis c’est tout.
Si vous n’avez encore jamais fait de Pull Request (PR), la lecture du tutorial Github Understanding the GitHub Flow est sûrement un bon point de départ.
Si vous n’aviez pas encore de compte Github, en voici une bonne introduction.
Pour le projet, nous utilisons le workflow suivant :
- Le projet principal ne possède qu’une branche
main. - Chaque participant réalise un fork du dépôt principal puis ouvre une branche depuis son fork pour chaque nouvelle feature.
- Une PR est créée depuis la branche du fork vers la branche
maindu dépôt principal.
Si vous vous sentez un peu perdu.e, la lecture de Using the Fork-and-Branch Git Workflow devrait vous rendre plus serein.ne.
Vous trouverez aussi d'autres informations sur les PR sur le dépôt coding-caen-camp.
Mais voici quelques conseils qui peuvent les rendre encore meilleures :
- Faites des commits courts et bien commentés.
- Faites des PR courtes, toute une tache (une issue) n’a pas forcement besoin d’être adressée dans une seule PR.
- Faites référence à l’issue que la PR adresse.
- N’hésitez pas à joindre des captures d’écran, fixes ou animées.
- Ajouter une description et une todo list en ouvrant la PR.
- N’attendez pas que la PR soit terminée pour l’ouvrir : la communauté viendra plus facilement en aide en découvrant tôt la PR.
- Utilisez les labels
WIP(Work In Progress) etRFR(Ready For Review) pour indiquer l’avancement de la PR. - dernier point : tous les textes (titre, description, commentaires, etc.) sont fait en français. En effet, même si la norme en opensource c’est l’anglais, nous avons collectivement décidé d’utiliser le français pour le projet.
Vous trouverez d'autres bonnes pratiques sur le dépôt coding-caen-camp.
Le système d’issues du Github est très bien pensé et permet de facilement réagir, commenter, noter... Donc si une issue vous intéresse mais qu’elle ne vous semble pas claire, c’est directement dans l’issue que vous pouvez poser des questions.
Si vous avez commencé une PR, mais que vous êtes bloqué, vous pouvez écrire un commentaire dessus décrivant votre problème et ajouter le label Demande d'aide ❓.
Il existe un channel coding-caen-camps sur le slack Web@Caen. N’hésitez pas à demander une invitation puis à y poser vos questions.
Le wiki d’un projet est souvent difficile à maintenir. C’est portant une manière simple et efficace de noter des « astuces » et autres commentaires documentant la vie du projet. Vous pouvez aller y jeter un coup d’œil, quelquefois qu’une bonne âme se serait donné la peine d’y noter quelque chose.
Nous nous réunissons si possible une fois par mois pour passer quelques heures ensemble. Pour être tenu au courant des prochaines sessions, le plus simple est de s’inscrire sur la newsletter des CaenCamp et/ou de nous suivre sur Tweeter