📖 merge documentation from the wiki in the folder doc

This commit is contained in:
tykayn 2020-08-11 18:54:00 +02:00
parent f358120516
commit c689a679e2
13 changed files with 490 additions and 5 deletions

View File

@ -1,3 +1,42 @@
# Framadate - funky version
FR: Un logiciel libre de sondage fait par les contributeurs de l'association Framasoft, avec une API backend.
EN: A libre polling software made by contributors around the French association Framasoft.
This version uses a brand new backend API.
## Pour débuter - getting started
[lire la doc pour débuter votre Funky Framadate](doc/GETTING_STARTED.md)
## Documentation
FR: Toute la documentation est disponible [dans le dossier "doc"](/doc), principalement en Français.
EN: All documentation is available in the "doc" folder, mainly in French because reasons.
* Meeting notes
* Getting Started (yarn start / npm start)
* How to contribute
* Architecture
* Translation i18n
* Accesibility
* Licence GNU affero V3
# Version funky framadate
* [Spécifications](docs/cadrage/specifications-fonctionnelles)
* maquettes par @maiwann : https://scene.zeplin.io/project/5d4d83d68866d6522ff2ff10
* vidéo de démo des maquettes par @maiwann : https://nuage.maiwann.net/s/JRRHTR9D2akMAa7
* discussions sur framateam canal général : https://framateam.org/ux-framatrucs/channaels/framadate
* discussions techniques côté développeurs : https://framateam.org/ux-framatrucs/channels/framadate-dev
* [notes de réunion](notes-de-reunion)
* [traductions](traductions)
# Documentations sur Angular
* `{- sur sass -}` (on va utiliser CSS, si angular permet d'avoir des variables CSS, @newick)
# Exemple de maquette de la nouvelle version
![funky_framadate_maquette](uploads/535da7c3a5ce5fae67b2b497bdc4631d/funky_framadate_maquette.png)
## LIBRARIES USED
| status | lib name | usage |
@ -29,11 +68,6 @@
This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 8.2.1.
# Framadate
A libre polling software make by contributors around the French association Framasoft.
## Development server
Run `yarn start` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
## Code scaffolding

View File

@ -0,0 +1,39 @@
# Comment contribuer à Framadate funky ?
Il existe des tas de façons de contribuer à un logiciel libre comme Framadate. Vous pouvez __discuter__ avec d'autres personnes de ce que vous souhaiteriez voir naître dans le logiciel, __essayer__ de l'utiliser dans sa version expérimentale, __mettre en place une démo__ ou un service publiquement utilisable, __écrire__ des modifications de code, proposer de l'aide de toute sorte, [traduire les textes](cadrage/i18n.md), vérifier l'accessibilité, lire la [documentation d'architecture](../doc/cadrage/architecture.md) etc...
* Avoir un compte Framateam, et Framagit si vous souhaitez contribuer au code
* Examiner les tickets
Discuter avec les autres membres participant, sur un ticket en particulier et aussi dans les canaux de framateam
* Une fois d'accord avec les autres, mettre à jour votre dépot de travail local
* Utiliser la branche dev
* Faire une branche dédiée à vos modifications
`git checkout -b ma-description-de-fonctionnalite`
* Faire une merge request sur framagit qui sera soumise à la revue de code par les pairs du projet.
* Continuer à interagit avec les autres membres
# Qui veut faire quoi?
* maiwann : maquettes, UX
* tykayn : développeur front end, JS & styles
* newick : intégrateur dans la vraie vie
* llaq : plutôt HTML / css et un peu de développement en php
* talone : plutôt coté JS
* tcit : dev tout qui connait bien le backend de Framadate actuel
* pouhiou : soutien moral
* come_744 : git, découverte d'angular
* arnaldo : php, découverte du libre
* elbuffeto : l'intégration HTML/CSS, accessibilité
* l4pin : un peu de front JS, beaucoup de back
* wadouk : dev compilé (elm, haskell, scala)
* cbossard : dev (plutôt backend), java/javascript, avec un peu de temps en ce moment
* seraf : dev fullstack (plutôt front), JS (Angular, VueJS, Svelte), PHP (Symfony, ApiPlatform), Java (Spring)
# Liens utiles:
* Discussion : https://framateam.org/ux-framatrucs/channels/framadate
* Repo front/dev : https://framagit.org/framasoft/framadate/funky-framadate-front/tree/dev
* Repo back : https://framagit.org/framasoft/framadate/framadate
* Maquettes Zeplin : demander l'accès à maiwann
* La démo : https://framadate-api.cipherbliss.com/
* Vidéo de présentation : https://nuage.maiwann.net/s/JRRHTR9D2akMAa7

20
doc/GETTING_STARTED.md Normal file
View File

@ -0,0 +1,20 @@
# Pour débuter - getting started
Clonez le dépot, installez les dépendances, et lancez le serveur local qui se recharge lorsque vous sauvegardez des fichiers dans le dépot. Les fois suivantes vous n'aurez qu'a lancer yarn start.
```bash
# clone the repo
git clone https://framagit.org/framasoft/framadate/funky-framadate-front.git
cd funky-framadate-front
# install yarn
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt-get update && sudo apt-get install yarn
yarn install --pure-lockfile
yarn start
# and now check your browser http://localhost:4200
```
Pour interagir avec la base de données, il vous faudra également faire démarrer l'API Symfony de backend dans l'autre dépot, qui se lance par défaut sur le port 8000.
# Pas de config docker
Nous n'avons pas actuellement de config docker qui solutionnerait tout ça, les merge request sont les bienvenues! :)

View File

View File

@ -0,0 +1,21 @@
# Accessibilité
Vérifiez toujours que ce que vous développez est Accessible pour des personnes aux handicaps divers tels que le préconise le WECAG.
https://www.w3.org/Translations/WCAG20-fr/
Quelques lignes à vérifier:
* Couleurs contrastées
* ordre des liens cohérent
* textes des liens éloquents
* textes alternatifs aux images les décrivant
* possibilité de changer la taille des textes et le thème visuel
* couleurs lisibles pour les personnes daltoniennes
* raccourcis claviers. alt+t pour passer a un autre thème visuel par exemple.
* attributs aria pour les lecteurs d'écran
* performance de chargement pour les petits débits
* server side rendering
* pas d'éléments perdus en dehors de l'écran, faites du mobile first
* parcimonie: si un élément n'est pas prévu pour être montré sur petit écran, ne le mettez pas sur grand écran sous prétexte qu'il y a plus de place.
* less is more
* système de recherche basique
N'ayez pas peur de demander de l'aide

View File

@ -0,0 +1,13 @@
# Architecture de Framadate
* Documentation de référence dans le dossier "doc" de ce dépot.
* Frontend généré avec Angular CLI
* chaque commit sur ce dépot passe les contrôles de format de Husky avant de pouvoir être envoyé.
* Doc sur l'api du nouveau backend à utiliser pour les appels REST du front funky : https://framagit.org/tykayn/date-poll-api/wikis/home
toujours se référer à la sortie de la commande de symfony `bin/console debug:router` du dépot back.
ancien backend en PHP sans framework ici pour mémoire : https://framagit.org/framasoft/framadate/framadate
# Schéma de base de données du backend
https://framagit.org/framasoft/framadate/funky-framadate-front/-/wikis/uploads/9d9a82cc6d7c6efea073b64d3667dc9b/framadate-api.png
png créé avec sqlfairy https://www.cipherbliss.com/exporter-une-visualisation-de-son-schma-sql/

13
doc/cadrage/i18n.md Normal file
View File

@ -0,0 +1,13 @@
# Internationalisation - i18n
Toutes les chaînes de texte doivent être disponible en minimum deux langues: Français et Anglais.
La documentation a été pensée pour être compréhensible en premier lieu par des personnes francophones, le projet étant issu de Framasoft et de personnes uniquement Francophones, nous avons jugé que c'était le moyen le plus efficace pour le faire grandir.
Voir les fichiers src/assets/i18n [EN.json](/src/assets/i18n/EN.json) et [FR.json](/src/assets/i18n/FR.json)
La traduction se base sur un système de clés-valeur.
Les clés sont entrées dans les templates html, et c'est la config d'Angular qui les traduit selon la langue demandée par le visiteur du site.
Chaque fichier de traduction est déclaré dans le [AppModule](../../src/app/app.module.ts) avec le module @ngx-translate. Examinez l'exemple pour rajouter votre propre traduction.
Utilisez des sous groupes dans vos traductions afin de mieux segmenter les chaines de caractère par page et selon le sens qu'elles sous tendent.

View File

@ -0,0 +1,108 @@
# Spécifications fonctionnelles de Framadate
[[_TOC_]]
![Diagramme des cas d'utilisations décrits dans la suite du document](uploads/uml/diagramme_cas_utilisation.png)
# Glossaire
| Terme | Signification |
| :--- | :--- |
| Créateur | Personne ayant créé le sondage |
| Participant | Personne invitée à participer ou ayant participé |
| Archivage | Empêcher votes et commentaires mais conserver les résultats |
| _Slug_ | Partie le l'URL identifiant un sondage de manière unique |
# Fonctionnalités actuellement dans framadate legacy et à conserver
## Généralités
Il existe deux types de sondage. Le type «dates» est adapté à la proposition de dates (voir [§plages horaires](#plages-horaires)) et le type «texte», plus généraliste, ne contient que du texte. Ce choix est l'un des premiers choix effectués lors de la création d'un nouveau sondage.
Deux types d'acteurs sont distingués : la personne ayant créé le sondage et les personnes qui répondent au sondage. Ces deux types d'acteurs n'ont pas les mêmes droits sur le sondage : la personne ayant créé le sondage est la seule ayant des droits d'administration sur celui-ci, en plus des droits des participants. En particulier, les droits d'administration permettent d'ajuster les droits des participants.
## Création d'un sondage
Il est nécessaire de fournir un email lors de la création du sondage. Cela permet aux créateurs de sondages de pouvoir obtenir via email la liste des sondages qu'ils ont créés.
Il est possible de choisir le _slug_ dans l'URL du sondage, à condition que ce _slug_ soit disponible.
Le sondage reste modifiable après sa création.
### Plages horaires
Les sondages de type «dates» permettent de proposer des jours et des plages horaires pour chaque journée.
Pour faciliter la saisie des dates proposées, il est demandé si les plages horaires sont les mêmes chaque jour ou si elles sont différentes selon les jours. Dans le premier cas, les plages horaires sont demandées uniquement pour le premier jour et sont automatiquement reproduites sur les autres jours.
Toujours pour faciliter la saisie des propositions, il est possible d'ajouter plusieurs jours consécutifs en sélectionnant le premier et le dernier jour plutôt qu'en sélectionnant chaque jour un à un.
## Participation à un sondage
### Votes
Les participants n'ont pas besoin de créer un compte ou de fournir leur email pour participer à un sondage.
Le créateur du sondage peut protéger le sondage par un mot de passe. Sans ce mot de passe, il est impossible de voir le sondage, donc impossible d'y voter. Attention cependant, le sondage est stocké en clair dans la base de données et ne bénéficie donc d'aucun chiffrement. *# Le mot de passe, lui, est-il chiffré?*
Le créateur du sondage choisit de permettre ou non les modifications des votes sur le sondage. Il a le choix entre les trois formules suivantes :
* ne pas permettre de modifier de réponse;
* permettre de modifier uniquement sa propre réponse a un sondage (modalités d'identification encore non déterminées);
* permettre de modifier toute réponse à un sondage (y compris celles des autres).
### Commentaires
Les participants au sondage ont la possibilité de créer des commentaires sur le sondage. Seule la personne ayant les droits d'administration sur le sondage peut modifier les commentaires.
## Résultats
Selon la configuration du sondage, les résultats peuvent n'être accessibles qu'à la personne ayant un accès d'administration ou bien être publics. Les personnes pouvant accéder aux résultats du sondage peuvent exporter ces résultats au format CSV.
## Emails
Lorsqu'une personne crée un sondage, un email reprenant les informations du sondage ainsi que les URL uniques servant à le modifier (lien d'administration) et à y participer (lien à transmettre aux participants) lui est envoyé. De plus, elle peut choisir de recevoir des emails lors d'un nouveau vote ou commentaire sur le sondage.
Une personne ayant créé au moins un sondage peut demander à recevoir par email la liste des sondages qu'elle a créés en utilisant cette adresse email.
## Stockage et export de données
Les données sont stockées en clair sur le serveur. L'archivage (resp. suppression) automatique des sondages est effectué via cronjob 90 (resp. 120) jours après sa création. Il est possible pour l'administrateur d'un sondage de modifier la durée avant archivage et la suppression automatique suit toujours de 30 jours la date d'archivage.
L'export d'un sondage et des résultats d'un sondage est possible au format CSV.
# Nouveautés principales
* Accessibilité renforcée.
* Traduction dynamique de toutes les phrases en choisissant la langue dans le menu.
* Adapté aussi bien sur mobile que grands écrans à haute ou faible densité de pixels.
* Anti-spam de commentaires.
* Anti-spam de vote.
* Tests unitaires et end-to-end.
* Couverture de test.
# Nouveautés secondaires
* Choix de réponses possibles. Proposer de ne répondre que «oui» ou rien, ou aller dans la nuance en proposant «oui», «peut-être», «non», « ? ». *# Redondance ou le choix de réponses possibles de la première phrase concerne un autre choix?*
* Insertion d'images dans le sondage de type texte, avec des URL uniquement. Une seule image par question possible ou rien.
* Thème sombre.
* Boutons pour copier dans le presse-papier les liens publics et privés / admin des sondages.
# Idées pour de futures améliorations (pertinence à vérifier)
* Gagner en vie privée en chiffrant certaines informations?
* À réfléchir : permettre à Framadate de faire entrer à des gens plusieurs plages de temps de disponibilité et le service déduit quelles sont les plages de temps favorables (calcul d'intersection sur des lignes discontinues). Cela pourrait être avec divers niveaux de détail. Comme https://omnipointment.com/ (qui est un logiciel privateur)
* SSO du fédiverse?

View File

@ -0,0 +1,39 @@
Framadate suivi - (__date de réunion__)
========================================
###### tags: #framadate, #suivi
> Participants à la réunion:
*
*
*
## État des lieux
### > Où on en est
https://framagit.org/framasoft/framadate/funky-framadate-front/-/boards
> Quel est le projet ? Quels sont les enjeux ?
> Quelles méthodes de travail ?
> Quel niveau de qualité ? standards et de bonnes pratiques ?
> *
> Quelles priorités ?
> *
> Qui veut faire quoi ?
> *
## Notes de réunion
-
## Trucs à faire
-
## Décisions prises
-
## Ressources
* Discussion : https://framateam.org/ux-framatrucs/channels/framadate
* Repo front/dev : https://framagit.org/framasoft/framadate/funky-framadate-front/tree/dev
* Repo back : https://framagit.org/framasoft/framadate/framadate
* Maquettes Zeplin : demander l'accès à maiwann
* La démo : https://framadate-api.cipherbliss.com/
* Vidéo de présentation : https://nuage.maiwann.net/s/JRRHTR9D2akMAa7

129
doc/reunions/2019_08_09.md Normal file
View File

@ -0,0 +1,129 @@
# notes du 9/8/2019 avec Mumble
À discuter :
discussion via framatalk ? plutôt mumble !
Se connecter à mumble.tcit.fr. Il n'a pas de mot de passe et il y a un salon Framadate ouvert.
qui peut/veut faire quoi ?
tykayn: dev front end, JS & styles
newick : intégrateur dans la vraie vie
llaq : plutôt HTML
talone : plutôt coté JS
on ne s'occupe toujours que du front ?
[newick] Est-ce que tout le monde est ok sur le fait de faire que le front et pas tout ?
llaq : pas de souci avec le back, donc pourquoi le changer ?
Ok on y touche pas
repartir de 0 ?
Je parle de funky framadate
llaq : Pourquoi pas recommencer car c'est bien différent des maquettes
newick : On est toujours en mode "MVP", on fait ça pour tester les maquettes et ensuite seulement on le connecte au back-end ?
maiwann : Ouip tant que ça reste cohérent niveau expérience de l'utilisateur
newick : C'est plutot coté JS qu'il faut voir… talone ?
Talone : on peut faire des choses, je maitrise pas php
llaq : moi non plus
talone : il y a des contributeurices de framadate ici ?
maiwann : nope :x
newick : on peut avancer comme ça, surtout sur le front et ensuite on verra le back ?
talone & llaq : oui on peut faire ça
[tentative de tykayn de nous rejoindre]
pourquoi y'a des pages php dans le dossier front end ?
newick : C'est dans le dossier principal, pas dans funky
maiwann : donc a priori rien d'obligatoire ?
API de backend existe t elle?
llaq : nope ^_^
Sass, css, autre ?
https://css2sass.herokuapp.com/ pour convertir le css actuel vers du sass
intérêt de Bootstrap / frameworks ?
Angular cli pour se concentrer sur des composants front end
Boostrap a priori c'est pas forcément nécessaire, newick assez à l'aise pour ne pas en avoir besoin dans HTML / CSS
Composants <3 Atomic design <3
tykayn : propose de faire une démo
(Beaucoup de discussion sur les framework front, j'ai pas tout compris ce qu'il se passait donc mes notes sont très limitées !)
En gros, on fait du Angular et chacun intègre son truc indépendamment
Invitation sur funkyframadate, on repart de 0 !
La suite
remplissons le wiki et les board d'issues
on zieute la démo et on voit ce qu'on fait ensuite
--------
# Questions notées par Come.
Suite au visionnage de la vidéo de présentation de maiwann (Framadate_Presentation_maquettes.flv), des questions ont été levées :
* Quel est l'intérêt de différentier les dates limites de modification et vote? Pourquoi appelle-t-on cela archivage?
* Peut-on écrire plus explicitement que le nom du créateur, s'il est renseigné, est affiché à ceux qui répondent?
* Lors de la validation du vote, peut-on mettre davantage en avant l'importance de l'URL d'édition afin d'éviter la fermeture machinale (par réflexe) du popup?
* Pour la vue des réponses, pourquoi ne pas mettre pour tous les utilisateurs les petites icônes actuellement réservées aux daltoniens? On économiserait alors un champ.
* Quitte à faire la chasse aux clics, pour les menus déroulants à deux options (du type «je veux» / «je ne veux pas») qui nécessitent deux clics pour commuter, pourquoi pas une commutation en un clic; comme une check-box mais avec du texte à la place du check? Bien-sûr, ceci à condition que les champs conditionnels ne soient pas vidés lorsqu'ils disparaissent.
* Y a-t-il des champs obligatoires? Si oui, comment les matérialiser?
* En cas d'erreur à la validation du formulaire (pour cause de champ vide ou format incorrect par exemple), on affiche systématiquement le message d'erreur en orange (cf. écran sondage_date_intervalle) en dessous du champ concerné?
* Quel est l'état de focus sur les champs? Celui par défaut du navigateur?
* Étant donné qu'il y a plusieurs étapes dans la création du sondage, ne faudrait-il pas les indiquer au début de la page? Ex : 1/3, 2/3, 3/3 (je tire ça des bonnes pratiques opquast)
* Dans le récapitulatif à la fin, pourquoi ne rappelle-t-on pas également le titre et la description du sondage créé?
Les boutons:
* Quel est l'état de focus sur les boutons?
* Sur l'écran «Mot de passe», le bouton «Voir» est-il immédiatement actif ou on attend d'avoir tapé la première lettre? Une fois qu'on a cliqué sur «Voir», est-ce que le contenu du bouton devient «Masquer»?
* Dans ta vidéo tu précises que le popup pour ajouter l'intervalle de dates se situe en dessous du calendrier pour qu'on puisse voir les dates préalablement sélectionnées, mais je pense que sur mobile ça va être compliqué : ça signifierait que le popup se situe très bas dans l'écran, il n'y aurait que le titre visible sur les téléphones de petite taille.
* Dans les écrans de réponse au sondage date, quelle est la règle pour l'abbréviation des dates? Des fois c'est le jour qui est abrégé, des fois le mois.
* On part sur une version desktop à partir de 768px? Je demande, car tes maquettes desktop font 602 px de large et je ne sais pas si c'est délibéré ou non.

View File

@ -0,0 +1,68 @@
Framadate suivi - Avril 2020
==
###### tags: `framadate` `suivi`
> Participants à la réunion: Maiwann / Tykain / Côme / Seraf
## État des lieux
> Où on en est sur la version funky ?
https://framagit.org/framasoft/framadate/funky-framadate-front/-/boards
> Quel est le projet ? Quels sont les enjeux ?
- Avoir un truc utilisable (sur téléphone !)
- Graphiquement plus élégant
> Quelles méthodes de travail ?
- Une refonte ergonomique avant de faire des tests utilisateurs pour vérifier que la nouvelle interface est chouette
> Quel niveau de qualité ? standards et de bonnes pratiques ?
- Une refonte graphique, utilisable sur mobile
- De l'internationalisation
- Un logiciel accessible
> Quelles priorités ?
- Cycle de vote à finir
> Qui veut faire quoi ?
## Notes de réunion
> Le nom semble peu approprié depuis l'apparition des nouvelles fonctionnalités.
Suggestions :
- Framapool
- FramEnquête
- Framasondage
> Idée de nouvelle fonctionnalité (pour plus tard hein :D )
- Chaque utilisateur indique ses disponibilités et le service renvoie les plages pour lesquelles le plus de personnes sont disponibles.
## Trucs à faire
- Gitlab CI : exécuter les tests automatiquement
- envoi de mail au créateur du sondage
- cafouillage entre front & back quand édition d'un sondage (à préciser par tykain)
- vérifier l'accesibilité du formulaire
- prompt de modale pour accès par mot de passe a un sondage privé
## Remarques
Il est difficile d'entrer dans le projet en absence de spécifications écrites. (seraf)
## Décisions prises
- Vérifier que chacun.e arrive à faire tourner le projet
- Chacune choisit des issues / tickets adaptés à ce qu'il a envie de faire
## Ressources
* Discussion : https://framateam.org/ux-framatrucs/channels/framadate
* Repo front/dev : https://framagit.org/framasoft/framadate/funky-framadate-front/tree/dev
* Repo back : https://framagit.org/framasoft/framadate/framadate
* Maquettes Zeplin : https://scene.zeplin.io/project/5d4d83d68866d6522ff2ff10
* La démo : https://framadate-api.cipherbliss.com/
* Vidéo de présentation : https://nuage.maiwann.net/s/JRRHTR9D2akMAa7

View File

@ -1,4 +1,5 @@
#!/bin/bash
# this script is used on cipherbliss.com to show a demo, customize it to make your own demo
git pull origin develop
yarn install --pure-lockfile