Plume est surtout codé en Rust. Le back-end utilise Rocket et Diesel. Le front-end est également en Rust, grâce à WebAssembly. Les feuilles de style sont écrites en SCSS.
Si vous voulez aider au code mais que vous ne savez pas par où commencer,vous pouvez essayer de trouver un problème qui vous intéresse (GitHub).
Ensuite, faites un fork de Plume (si vous ne l'avez pas déjà fait), récupérez (git clone) votre fork et commencez une nouvelle branche avec git checkout -b NOM-DE-LA-BRANCHE. Vous pouvez désormais commencer à travailler sur votre issue.
Une fois que vous avez un code fonctionnel, lancez git add FICHIERS MODIFIES (ou git add . pour tous les ajouter), et ensuite git commit. Écrivez un message expliquant vos changements, et faites git push origin NOM-DE-LA-BRANCHE
pour téléverser votre travail sur Gitea ou GitHub. Ouvrez l'URL qui apparaît dans la sortie de cette dernière commande pour ouvrir
une requête de pull, que nous allons ensuite vérifier, et finalement fusionner.
Mise en place de l'environnement de développement
Veuillez consulter le guide d'installation. Choisissez de compiler le Plume
à partir de la source quand on vous le demandera. Au lieu d'utiliser cargo install, utilisez cargo run qui lance une version fraîchement compilée et prête pour le débogage.
Il est recommandé d'activer la fonctionnalité debug-mailer en particulier si vous utilisez les e-mails pendant le développement. Vous pouvez le faire en passant l'option --feature debug-mailer à cargo. Lorsqu'elle est activée, les courriers seront envoyés sur la sortie standard au lieu d'être envoyés réellement.
Migrations
Les Migrations sont des fichiers que l'on peut utiliser pour mettre à jour le schéma de base de données (par exemple pour ajouter un nouveau champ à un modèle).
Pour créer de nouvelles migrations, vous aurez besoin d'un outil appelé diesel, qui peut être installé avec :
cargo install diesel_cli --no-default-features --features DATABASE --version '=1.3.0'
Après cela, pour créer une migration, aussi bien pour PostgreSQL que pour SQlite, vous devez exécuter ces deux commandes :
MIGRATION_DIRECTORY=migrations/postgres diesel migration generate NOM
MIGRATION_DIRECTORY=migrations/sqlite diesel migration generate NOM
Où NOM est le nom que vous voulez donner à votre migration, en un seul mot, par exemple ajouter_role_utilisateur.
De nouveaux fichiers seront générés dans migrations/postgres et migrations/sqlite, appelés up.sql et down.sql.
Le premier devrait lancer la migration actuelle et le deuxième permettra de l'annuler plus tard.
Vous pouvez également exécuter du code Rust dans les migrations, en l'écrivant dans les commentaires commençant par #!, et enveloppé dans une fermeture prenant en argument une connexion de base de données et un chemin vers le répertoire courant. Vous pouvez accéder aux modules plume-models avec le module super .
Voici un exemple :
--#!|connexion: &Connection, chemin: &Path| {
--#! println!("Migration en cours depuis {}", chemin);
--#! println!("L'administrateur de l'instance est @{}", Instance::get_local(connexion).unwrap().main_admin(connexion).unwrap().name());
--#! Ok(())
--#!}
Si votre fonction est trop longue, vous pouvez également la mettre dans plume-models, et simplement donner son identifiant complet dans le commentaire:
--#! crate::migrations::functions::ma_fonction_migration
Pour exécuter les migrations, vous pouvez utiliser plm migration run. Pour les annuler et les relancer, utilisez plm migration redo.
Essayer la fédération
Pour essayer la fédération, vous devrez configurer une autre base de données, appartenant également à l'utilisateur “plume” , mais avec un nom différent. Ensuite, vous devrez aussi configurer cette instance.
La façon la plus simple de faire est probablement d'installer plm et plume globalement (comme expliqué
ici), mais avec l'option --debug pour éviter un temps de compilation trop long. Ensuite, créez une copie de votre fichier .env dans un autre répertoire, et modifiez les variables DATABASE_URL
et ROCKET_PORT . Copiez ensuite les fichiers de migration dans ce nouveau répertoire et exécutez-les.
plm migration run
Configurer la nouvelle instance avec plm comme expliqué ici.
Maintenant, tout ce dont vous avez besoin pour que vos deux instances puissent communiquer est un faux nom de domaine avec HTTPS pour chacune d'entre elles. La première étape à effectuer sur votre machine locale est
d'éditer votre fichier /etc/hosts pour créer deux nouveaux alias en ajoutant les lignes suivantes.
127.0.0.1 plume01.localhost
127.0.0.1 plume02.localhost
Maintenant, nous devons créer des certificats SSL pour chacun de ces domaines. Pour ça nous utiliserons mkcert. Voici les instructions pour l'installer.
Une fois que vous l'avez installé, lancez les commandes suivantes.
mkcert -install
mkcert plume01.localhost
mkcert plume02.localhost
Enfin, nous avons besoin d'un reverse proxy pour charger ces certificats et rediriger chaque domaine vers l'instance Plume correspondante. Nous utiliserons Caddy car il est vraiment simple à configurer, mais vous pouvez utiliser des alternatives avec lesquelles vous êtes plus à l'aise.
Pour installer Caddy, veuillez consulter leur site. Ensuite, créez un fichier appelé Caddyfile dans le répertoire où vous avez lancé mkcert et écrivez ce qui suit dedans.
plume01.localhost {
reverse_proxy localhost:7878
tls plume01.localhost.pem plume01.localhost-key.pem
}
plume02.localhost {
reverse_proxy 127.0.0.1:8787
tls plume02.localhost.pem plume02.localhost-key.pem
}
Finalement remplacez les ports dans les blocs proxy par ceux des deux instances lancées, puis lancez caddy. Vous pouvez maintenant ouvrir votre navigateur et charger https://plume.localhost et https://plume.localhost.
Exécution des tests
Pour lancer les tests, utilisez DATABASE_URL et lancez les migrations d'abord.
Pour exécuter les tests de plume-models utilisez RUST_TEST_THREADS=1, sinon les tests seront exécutés simultanément, ce qui provoque des erreurs car ils utilisent tous la même base de données.
Internationalisation
Pour marquer une chaîne comme traduisible entourez la avec la macro i18n!. Le premier argument doit être le catalogue d'où les traductions seront chargées (généralement ctx.1 dans les modèles), le second la chaîne à traduire. Vous pouvez spécifier les arguments de format après un ;.
Si votre chaîne de caractères varie selon le nombre d'éléments, fournissez la version plurielle comme troisième argument, et le nombre d'éléments comme premier argument de format.
Vous pouvez trouver des exemples d'utilisation de cette macro ici.
Il n'est pas nécessaire de fournir des traductions individuelles des chaînes entourées par i18n! dans les demandes de tirage.
Les chaînes seront envoyées à un service web tiers et traduites automatiquement dans une autre étape.
Ajouter une nouvelle langue
Les gestionnaires du projet Crowdin peuvent ajouter de nouvelles langues à la liste des langues cibles. Mais pour que ces nouveaux langages soient également visibles dans l'interface, il faut modifier le code source.
Tout d'abord, assurez-vous que le fichier .po correspondant est présent dans po/plume, et dans po/plume-front.
Dans le cas contraire, demandez à une personne qui a accès à la clé API Crowdin (comme un.e gestionnaire ou un.e propriétaire de Crowdin) de la récupérer avec l'outil en ligne de commande de Crowdin.
Pour trouver un.e gestionnaire, regardez la liste dans la barre latérale de cette page. Ces personnes sont des gestionnaires parce qu'elles étaient suffisamment impliquées dans le projet, et en particulier dans le processus de traduction. If you want to become a manager on Crowdin too, ask us on Matrix.
Ensuite, dans src/main.rs et plume-front/src/main.rs, ajoutez le code correspondant à la langue dans la macro init_i18n!.
Si vous ne savez pas quel code ajouter pour votre langage : c'est le nom du fichier .po sans l'extension.
Voici un exemple d' une demande de tirage qui ajoute le Persan.
cargo check pour s'assurer que tout compile et que vous avez bien fini !
Travailler avec la partie utilisateur
Lorsque nous travaillons avec le front-end, nous essayons de limiter notre utilisation de JavaScript autant que possible. En fait, nous n'utilisons même pas JavaScript puisque notre front-end utilise aussi Rust grâce à WebAssembly. Mais nous espérons que Plume marchera avec aussi peu de JavaScript que possible, étant donné que lire un article (Le but premier de Plume) ne devrait pas demander beaucoup d'interaction avec la page.
Lors de l'édition des fichiers SCSS, il est bon de savoir qu'ils sont compilés par cargo également. Mais cargo peut être un peu lent, puisqu'il recompile tout Plume à chaque fois et pas uniquement les fichiers SCSS. Une solution est d'exécuter
cargo run en arrière-plan, et utiliser cargo build pour compiler votre SCSS, puis le stopper avant la fin de la compilation. Pour savoir quand votre SCSS a été compilé, attendez que cargo vous dise qu'il compile plume(bin) et non plume(build) (à côté de la barre de progression).
De plus, les modèles utilisent la syntaxe Ructe, qui est un mélange de Rust et HTML. Ils sont traduits en Rust et intégrés dans Plume, ce qui signifie que vous devez relancer cargo à chaque fois que vous changez les modèles.
Style de code
Pour Rust, utilisez le style standard. rustfmt peut vous aider à garder votre code propre.
Pour SCSS, les seules règles sont d'utiliser One True Brace Style et deux espaces pour indenter le code.
Pour JavaScript, nous utilisons le style standard JavaScript.
Pour les modèles HTML/Ructe, nous utilisons la syntaxe HTML5.