Enquête Nationale, Trois-Rivières et Sherbrooke, automne 2024

Cette enquête utilise la plateforme evolution⁠

Installation

Pour installer, il faut d'abord aller chercher le code de ce répertoire, ainsi que celui de la plateforme correspondante:

git clone https://github.com/chairemobilite/od_nationale_2024.git
git submodule init
git submodule update --init --recursive

La façon d'installer est la même que pour la plateforme evolution. Donc, suivre les instructions, sous la rubrique Installation, du README de la version d'evolution se trouvant dans le répertoire evolution qui a été téléchargée par la commande git submodule plus haut. Ce n'est peut-être pas la version la plus récente d'Evolution et les instructions sur la branche principale de la plateforme ne fonctionneront pas nécessairement.

Les instructions d'installation doivent s'exécuter à partir de la racine de ce répertoire et non dans le répertoire evolution.

Rouler l'application

L'enquête est composée de 2 applications distinctes: une pour les participants web uniquement et l'autre pour les administrateur, intervieweurs, etc. Chaque application peut être exécutée indépendamment de l'autre et chacune est composée de 2 parties: le code client et le serveur.

Application participant

Pour rouler l'application participant, il faut créer le paquet de déploiement du client et démarrer le serveur.

• yarn build:dev ou yarn build:prod permet de créer l'application client respectivement en mode développement, qui permet de facilement déboguer l'application, ou en mode production, qui est une version minifiée et plus performante.
• yarn start démarre le serveur sur le port 8080

Accéder à l'application participant au http://localhost:8080.

Application administrative

Pour rouler l'application administrative, il faut créer le paquet client et démarrer le serveur sur un autre port.

• yarn build:admin:dev ou yarn build:admin:prod permet de créer l'application client, respectivement en mode développement et production.
• HOST=http://localhost:8082 yarn start:admin --port 8082 démarre le serveur sur le port 8082.

Accéder à l'application participant au http://localhost:8082

Mettre à jour l'application

Pour mettre à jour l'application, il suffit d'aller chercher la dernière version de la branche. Il peut y avoir des changements à la version d'Evolution utilisée, il faut s'assurer de le mettre à jour aussi.

git checkout main
git pull origin main
yarn reset-submodules
yarn
yarn compile
yarn migrate

Contribuer à l'enquête

Pour contribuer à l'enquête et soumettre des changements, il faut passer par des pull requests.

• S'assurer d'avoir la version la plus récente de l'enquête, en suivant les instructions de la section précédente
• Créer une branche de travail: git checkout -b <nom de la branche>
• Effectuer les changements sur cette branche.
• Une fois la branche prête à être reviewée, l'envoyer upstream: git push origin <nom de la branche>
• Il est alors possible de créer une pull request sur github en allant sur le tab Pull requests du projet

Une pull request peut être un seul commit ou une branche complète. Dans ce dernier cas, chaque commit doit être indépendant et complet, avec un titre explicite. Les titres du genre Fix typo sont à proscrire.

Il est possible d'éditer un commit déjà fait pour le compléter ou fixer un typo. Si le commit à éditer est le dernier, simplement utiliser git commit --amend pour intégrer les changements actuels au commit.

Pour réécrire un historique de branche, par exemple pour ajouter à un commit précédent autre que le dernier, ou pour combiner des commits, il faut utiliser le rebase interactif git rebase -i HEAD~x où x est le nombre de commits à revoir.

Pour plus d'information sur les outils de git pour réécrire l'historique, consulter le manuel de git⁠.

Édition et mise à jour des traductions

La "source de vérité" pour les libellés de questions se trouve dans le fichier LibellesQuestions.csv. Après avoir éditer ce fichier avec les nouveaux libellés, les fichiers locales doivent être mis à jour en exécutant le script python suivant:

evolution/scripts/fillLocales.py --inputFile ./originalTranslation/LibellesQuestions.csv --localesPath ./survey/locales --overwrite [--namespace <nom de la section>]

Pour plus d'information sur les options de ce script, utiliser evolution/scripts/fillLocales.py --help.

Voici quelques instructions supplémentaires pour personnaliser les libellés:

Remplacements:

• {{nickname}} sera remplacé par le nom ou surnom de la personne
• {{assignedDate}} sera remplacé par la date du carnet de déplacement

Styles: Certains styles seront appliqués si le texte est encadré par les caractères suivants. Il doit y avoir un nombre pair de tels caractères pour que le style s'applique

• ** mettra le texte en gras
• __ mettra le texte en format bleu italique
• _green_ mettra le texte en vert
• _red_ mettra le texte en rouge

Fonctionnement des traductions finales

Cette enquête utilise les librairies i18next pour les traductions des étiquettes et messages d'aide des questions. Les fichiers qui contiennent ces strings sont dans le répertoire survey/locales. Il suffit d'éditer ces fichiers pour modifier les questions.

Pour les questions qui ont une formulation différente en mode "participant" et mode "intervieweur", il faut ajouter un 2e label du même nom que le premier, mais avec le suffixe _cati après. Pour les labels et les message d'aide multi-lignes, il faut passer une ligne dans le fichier yaml pour que le changement de ligne soit pris en compte. Voici un exemple de string avec 2 formulations:

AccessCode: >-
    Access code<br /><span class="_pale _oblique">Printed on the letter you
    received</span>
AccessCode_cati: >-
    What is your unique access code ?<br /><span class="_pale _oblique">You can
    find this in the letter you received.</span>

Pour aider à l'édition des étiquettes traduites, les utilisateurs de VS Code peuvent utiliser l'extension "i18n Ally". Les configurations appropriées sont déjà spécifiées dans ce repo, et le panneau "i18n Ally" à gauche permet de lister toutes les chaînes de caractères à traduire, permet de les dupliquer, les éditer, dans les 2 langues, etc.

Il est toutefois préférable d'utiliser le fichier csv pour les libellés de question s'y trouvant puisque les fichiers yml pourraient être réécrits par le script d'import des traductions.

Exécution des tests

L'enquête a quelques tests unitaires qui peuvent simplement s'exécuter avec yarn test.

Transit

Pour obtenir le fichier de busRoutes à partir des données GTFS importées dans une instance de transition, on peut exécuter la requête suivante:

D'abord, ajouter la fonction slugify (prise de https://medium.com/broadlume-product/using-postgresql-to-generate-slugs-5ec9dd759e88⁠):

CREATE EXTENSION IF NOT EXISTS "unaccent";

CREATE OR REPLACE FUNCTION slugify("value" TEXT)
RETURNS TEXT AS $$
  -- removes accents (diacritic signs) from a given string --
  WITH "unaccented" AS (
    SELECT unaccent("value") AS "value"
  ),
  -- lowercases the string
  "lowercase" AS (
    SELECT lower("value") AS "value"
    FROM "unaccented"
  ),
  -- replaces anything that's not a letter, number, hyphen('-'), or underscore('_') with a hyphen('-')
  "hyphenated" AS (
    SELECT regexp_replace("value", '[^a-z0-9\\-_]+', '-', 'gi') AS "value"
    FROM "lowercase"
  ),
  -- trims hyphens('-') if they exist on the head or tail of the string
  "trimmed" AS (
    SELECT regexp_replace(regexp_replace("value", '\\-+$', ''), '^\\-', '') AS "value"
    FROM "hyphenated"
  )
  SELECT "value" FROM "trimmed";
$$ LANGUAGE SQL STRICT IMMUTABLE;

Et la requête finale pour obtenir le feature collection à copier coller:

select jsonb_build_object(
			'type',       'FeatureCollection',
			'features', COALESCE(jsonb_agg(features.feature), '[]'::jsonb)
	) from
	(select jsonb_build_object(
			'type',       'Feature',
			'properties', json_build_object(
				'slug', slugify(concat(ag.acronym, '_', lines.shortname, '_', lines.longname)),
				'name', concat(ag.acronym, ' ', lines.shortname, ' ', lines.longname),
				'agencyId', ag.acronym,
				'shortname', lines.shortname,
				'sortableName', concat(lpad(lines.shortname, 5, '0'), ag.acronym)
			)
		) as feature from transition_od_nationale_2024.tr_transit_lines lines
	inner join transition_od_nationale_2024.tr_transit_agencies ag on ag.id = lines.agency_id
	 where lines.mode = 'bus'
	 order by ag.acronym, lines.shortname
	) as features

Housekeeping

Détection des fichiers non importés

Afin de garder le code clean et ne pas conserver de fichiers inutilisés, il est possible de détecter automatiquement ces fichiers et ensuite les supprimer manuellement avec le package node unimported⁠.

Le projet est configuré dans le fichier .unimportedrc.json et il suffit de rouler yarn unimported pour obtenir la liste des fichiers inutilisés.

Cette commande ne fonctionne toutefois pas pour les fichiers .json.

Note: Selon le README de ce projet, il n'est plus maintenu et il faudrait plutôt migrer vers knip. Mais unimported semble plus facile à configurer.