fusen v0.5: « inflatez » les tous !

Finie l’amnésie pour {fusen} ! La v0.5 lui permet maintenant d’avoir de la “mémoire”, ce qui va notamment vous permettre de gonfler simultanément l’ensemble de vos fichiers plats. Cette dernière version de {fusen} vise à offrir une expérience de développement de packages toujours plus fluide, pour les utilisateurs débutants comme pour les vieux routiers de son utilisation.

{fusen} continue sa route pour faciliter la vie des créatrices et créateurs de packages. L’un des principaux changements de cette nouvelle version est l’apparition d’un fichier de configuration permettant de répertorier les liens entre un fichier plat “parent” (dans le répertoire dev/) et ses fichiers “enfants” (dans les répertoires R/, tests/ et vignettes/). Ce fichier permet à {fusen} d’avoir maintenant de la mémoire et constitue la pierre angulaire d’une fonctionnalité majeure de la v0.5 : la possibilité de lancer de manière automatique un inflate_all() sur tous vos fichiers plats en même temps !

Pour les utilisateurs de {fusen} moins expérimentés, n’hésitez pas à consulter nos articles précédents, pour les plus chevronnés vous pouvez foncer vers la suite.

Nos articles précédents :

• Comment débuter avec {fusen}
• Trucs et astuces de la v0.4

Installation

{fusen} est disponible sur CRAN et développé sur GitHub. Vous pouvez accéder à la documentation complète sur cette page : https://thinkr-open.github.io/fusen/. Il apparaît également sur la page ThinkR r-universe si vous souhaitez installer la version de développement sans les contraintes de l’API GitHub.

Installer la version CRAN

install.packages("fusen")

Installer la version de développement

install.packages('fusen', repos = c('https://thinkr-open.r-universe.dev', 'https://cloud.r-project.org'))

{fusen} répertorie tous les fichiers de votre package

Sur les packages développés avec {fusen} >= v0.5, on note l’apparition d’un fichier de configuration dev/config_fusen.yaml. Ce fichier permet d’introduire la notion de “mémoire” dans {fusen}. Le fichier de configuration va répertorier les liens entre un fichier plat “parent” et ses fichiers “enfants”. Sa mise à jour est réalisée à chaque appel à la fonction inflate() sur un fichier plat donné. Les paramètres utilisés pour configurer l’appel à inflate() y sont également stockés.

Ceci va vous permettre de garder une trace du lien entre les fichiers plats, et tous les fichiers des répertoires R/, tests/ et vignettes/. Le fichier de configuration répertorie également tous les fichiers non issus d’un fichier plat, ce qui pourra vous donner une occasion de faire un peu de ménage dans votre package si besoin.

Je développe un nouveau package avec {fusen} v0.5.1, que dois-je faire ?

Rien de spécial, à part profiter directement des nouvelles fonctionnalités ! Le fichier de configuration apparaitra lors d’un premier appel à inflate() et se mettra à jour à chaque nouvel appel.

J’ai commencé un package avec une version de {fusen} antérieure à v0.5.1, que dois-je faire ?

Le plus simple est de lancer un fusen::inflate_all_no_check() et de suivre les instructions renvoyées par la fonction.

Il est probable que vous deviez :

1. Lancer un inflate() de chacun de vos fichiers plats avec cette version de {fusen}.
2. Lancer fusen::check_not_registered_files() pour lister les fichiers non répertoriés dans le fichier de configuration.
3. Vérifier le contenu du fichier dev/config_not_registered.csv.
4. Nettoyer votre package des fichiers listés à l’étape 3, si nécessaire.
5. Répertorier tous les fichiers restants encore non répertoriés avec fusen::register_all_to_config().

Tentez à nouveau un appel à fusen::inflate_all_no_check() ou fusen::inflate_all() et vous devriez pouvoir reprendre vos développements sereinement.

J’ai commencé un package sans {fusen}, que dois-je faire ?

Pour poursuivre votre package avec {fusen}, l’implémentation de vos nouvelles fonctionnalités devra se faire au sein d’un premier fichier plat. Une fois que c’est fait vous pouvez suivre la procédure décrite dans la section précédente.

A quoi ressemble le fichier de configuration ?

Le fichier de configuration, présent dans dev/config_fusen.yaml, liste tous les fichiers plats qui ont été gonflés, les fichiers créés lors de cette opération et les paramètres utilisés pour appeler la fonction inflate().
Les autres fichiers, non issus de fichiers plats, sont également répertoriés, sous une section nommée “keep”.

Voici ci-dessous un exemple de fichier de configuration :

flat_file1.Rmd:
  path: dev/flat_file1.Rmd
  R:
  - R/function1.R
  - R/function2.R
  tests:
  - tests/testthat/test-function1.R
  - tests/testthat/test-function2.R
  vignettes: vignettes/How-to-use-these-2-awesome-functions.Rmd
  inflate:
    flat_file: dev/flat_file1.Rmd
    vignette_name: First vignette to read
    open_vignette: false
    check: false
    document: true
    overwrite: 'yes'  
flat_file2.Rmd:
  path: dev/flat_file2.Rmd
  R:
  - R/function3.R
  - R/function4.R
  tests:
  - tests/testthat/test-function3.R
  - tests/testthat/test-function4.R
  vignettes: vignettes/Yet-another-vignette-to-read.Rmd
  inflate:
    flat_file: dev/flat_file2.Rmd
    vignette_name: Yet another vignette to read
    open_vignette: false
    check: false
    document: true
    overwrite: 'yes'
keep:
  path: keep
  R:
  - R/my_R_file1_from_my_previous_work.R
  - R/my_R_file2_from_my_previous_work.R
  tests:
  - tests/testthat/test-my_previous_work.R
  vignettes: vignettes/my_vignette_from_my_previous_work.Rmd

Ce fichier de configuration nous indique que le package contient 2 fichiers plats : flat_file1.Rmd et flat_file2.Rmd. Ceux-ci sont associés à 2 fichiers dans le répertoire R/, 2 fichiers dans le répertoire tests/ et 1 fichier dans le répertoire vignettes/, respectivement. Ces 2 fichiers ont été gonflés avec la dernière version de {fusen} car les paramètres utilisés pour l’appel à la fonction inflate() sont également listés.
Enfin, on retrouve dans la section “keep” des fichiers qui proviennent d’anciens développements réalisés sur ce package, et non réalisés avec {fusen}.

Et pour en savoir plus ?

Rendez-vous sur la vignette dédiée.

Comment gonfler tous mes fichiers plats en une seule fois ?

Votre package commence à comporter de nombreux fichiers plats et vous êtes lassés de devoir gonfler régulièrement “à la main” chacun de ces fichiers ? Ca tombe bien, avec cette version{fusen} vient la fonction inflate_all() !

Chaque appel à inflate() stocke dorénavant les paramètres d’appel de la fonction au sein du fichier de configuration mentionné précédemment. La fonction inflate_all() va réutiliser ces paramètres pour gonfler en série tous vos fichiers. Ceci implique qu’un fichier plat devra avoir été gonflé manuellement via inflate() avant d’être utilisable via inflate_all().

J’ai commencé un package avec une version de {fusen} antérieure à v0.5.0, que dois-je faire ?

Le fichier de configuration est absent de votre projet, l’appel à un inflate() sur chacun de vos fichiers plats va créér le fichier de configuration et le remplir.

Je connaissais déjà l’existence du fichier de configuration et j’ai commencé mon package une version de développement de {fusen} antérieure à la v0.5.1, que dois-je faire ?

Le fichier de configuration existe dans votre projet, il liste bien les liens entre les fichiers plats et les fichiers présents dans R/, tests/ et vignettes/ mais la section relative aux paramètres d’inflate() est vide ! Pour la remplir, il sera nécessaire de faire un appel manuel à inflate() pour chacun des fichiers plats.

Et pour en savoir plus ?

Rendez-vous sur la vignette dédiée.

Au final, c’est compliqué de passer à la nouvelle version de {fusen} ?

Pas du tout !

• Si vous commencez un nouveau package avec cette version de {fusen}, tout se fera de manière limpide.
• Si vous repartez d’un ancien package développé sans {fusen} ou avec une ancienne version de {fusen}, il ne vous faudra que quelques minutes pour rendre votre projet compatible avec cette version et pouvoir profiter de toutes les nouvelles fonctionnalités !

Avec {fusen} v0.5.1, vous aurez maintenant :

• Un résumé des liens entre les fichiers de votre package dans le fichier de configuration : ceci permet d’avoir un projet plus lisible et plus propre.
• La possibilité de gonfler tous vos fichiers plats à la fois : ceci offre un gain de temps et il n’y a plus d’oubli possible.

{fusen} et {attachment}

Le but du package {attachment} est de vous aider à gérer les dépendances durant le développement de votre package. {attachment} est utilisé par {fusen} lors de l’appel à un inflate() pour mettre à jour la documentation et les dépendances du package.

Avec {attachment} v0.4.0, on observe également l’apparition d’un fichier de configuration, similaire à celui utilisé par {fusen}. Pour une coopération optimale entre ces deux packages il est conseillé d’utiliser également cette version d’{attachment}.

Pour en savoir plus sur cette dernière version et sur la collaboration entre {fusen} et {attachment}, vous pouvez consulter ces ressources :

• {attachment} v0.4.0 : Des changements majeurs et un fichier de configuration pour une meilleure expérience
• Developpement de package avec {fusen} & {attachment} : charger les fonctions du flat, gérer les qmd et auto-remplissage du champ Remotes

Contenu du NEWS (v0.5.0 + v0.5.1)

Nouvelles fonctionnalités

Gonfler tous vos fichiers plats actifs

• inflate_all() utilise le fichier de configuration pour gonfler tous vos fichiers plats en une fois. Les options document et check sont ainsi lancées une seule fois pour tous vos fichiers plats. (#204, @ymansiaux)
• Ceci implique d’avoir lancé un inflate() au moins une fois pour chaque fichier plat.
• Ceci implique également d’avoir répertorié tous les autres fichiers qui étaient déjà présents dans le package avant cette version de {fusen} avec register_all_to_config().

Lister tous les fichiers créés par un inflate() et ses paramètres dans un fichier de configuration

• inflate() créé un fichier de configuration dev/config_fusen.yaml pour répertorier tous les fichiers créés en gonflant un fichier plat, ainsi que les paramètres utilisés dans l’appel à inflate(). (#198, @ymansiaux)

Publier le site de votre package sur Github

• Publier le site du package sur Github en utilisant la commande init_share_on_github()

Lister tous les fichiers créés par inflate() dans un fichier de configuration

• inflate() crée un fichier dev/config_fusen.yaml pour enregistrer tous les ficheir crées en gonflant le fichier plat correspondant. (travail initié dans #24)
• Migrer depuis un package non créé via {fusen} ou avec une version antérieure de {fusen} avec register_all_to_config().
• Créer ou mettre à jour le fichier de configuration à partir d’un data frame pour lister un ensemble de fichiers à conserver (même si ils ne sont pas issus d’un fichier plat).

Autres

• Autoriser plusieurs exemples pour une même fonction (#149)

Changements de ruptures

• Les arguments rmd et name de la fonction inflate() renvoient maintenant des erreurs (Dépréciés depuis la version v0.3.0).
• add_dev_history() était déprécié depuis la v0.3.0 en faveur de add_flat_template(). Maintenant, add_dev_history() ajoute seulement un fichier "dev_history.Rmd" dans le répertoire dev/.
• add_flat_template(template = "minimal") n’existe plus pour éviter la confusion entre un package minimal et un fichier plat minimal. En effet, maintenant il y a add_flat_template(template = "minimal_package") (add_minimal_package() également) ou add_flat_template(template = "minimal_flat") (add_minimal_flat() également).
• create_fusen() utilise toujours minimal comme minimal_package.

Changements majeurs

• create_fusen() et l’interface utilisateur RStudio permettent maintenant de faire en sorte que le paramètre flat_file nomme le premier fichier plat ainsi que la première fonction (en utilisant le template “minimal”).
• La vignette tips and tricks présente rapidement comment combiner {fusen} et {golem}. (#187)
• Les noms de fonctions incorrects obtenus via les addins ou add_flat_template() sont nettoyés avant d’être inclus dans le fichier plat pour suivre la règle du “underscore”.

Changements mineurs

• Mise à jour du fichier CONTRIBUTING.md pour mentionner l’usage des fichiers plats dans {fusen}
• Remplacement du nom du mainteneur à partir de fill_description() dans les exemples, modèles et tests (#155, @FlorenceMounier)
• create_fusen() “vaccine” le projet git créé (#171)
• Les exemples sous la documentation roxygen d’une fonction sont nettoyés des espaces supplémentaires après un #' vide pour éviter de détecter des différences via git diff causées par des linters ou stylers.

Correction de bugs

• Problème lié à l’utilisation de saut de ligne après le nom de la fonction dans les fichiers plats (#142, @FlorenceMounier)
• Si le répertoire du projet est renommé en "mon.package (Copie)", inflate() fonctionne toujours, même si ce n’est pas un nom de package valide. Ce qui importe c’est que le nom du package dans le fichier DESCRIPTION soit correct.
• Problème lié à l’utilisation de function( dans la documentation (#174, @FlorenceMounier)