From 477f840c269c4689ae3bbae0477f686b4ca0b703 Mon Sep 17 00:00:00 2001 From: infra-bot Date: Fri, 3 Jul 2026 11:18:51 +0200 Subject: [PATCH] docs: RFC surface d'API 0.5 (issue #33) Document de design a discuter, sans implementation : nom compare_datasets() + alias retrocompatible, objets d'options extract_opts()/engine_opts(), retour de classe datadiff_result (passed/report, depreciation de reponse/all_passed dupliques), fail_at unique, bascule lang en a la 0.5, cycle de depreciation en 3 versions. Les quick wins non cassants sont rattaches aux issues deja traitees (#16/#20/#25/#26/#27/#30). --- .Rbuildignore | 1 + dev/RFC-api-0.5.md | 117 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 dev/RFC-api-0.5.md diff --git a/.Rbuildignore b/.Rbuildignore index 293d000..48144d0 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -13,3 +13,4 @@ ^README\.Rmd$ ^doc$ ^Meta$ +^dev$ diff --git a/dev/RFC-api-0.5.md b/dev/RFC-api-0.5.md new file mode 100644 index 0000000..5fa6787 --- /dev/null +++ b/dev/RFC-api-0.5.md @@ -0,0 +1,117 @@ +# RFC : surface d'API datadiff 0.5 + +Statut : proposition a discuter (issue #33). Rien ici n'est implemente ; +les quick wins non cassants identifies sont listes en fin de document avec +leur issue de rattachement. + +## Constat + +La fonction centrale `compare_datasets_from_yaml()` a grossi par accretion : +17 parametres a plat, un nom qui ne reflete plus l'usage (le YAML est +optionnel depuis 0.1.5), un retour a 8 champs partiellement redondants, et un +melange de langues (arguments anglais, champ `$reponse` en francais, rapport +par defaut en francais, messages en anglais). + +## Proposition + +### 1. Nom et alias + +```r +compare_datasets(reference, candidate, key = NULL, rules = NULL, ...) +``` + +- `compare_datasets()` devient le point d'entree documente. +- `compare_datasets_from_yaml()` reste exporte comme alias retrocompatible + (one-liner qui delegue), documente dans une section "Legacy". +- `reference`/`candidate` remplacent `data_reference`/`data_candidate` + (les anciens noms restent acceptes par l'alias). + +### 2. Objets d'options pour les passe-plats + +Cinq parametres sont du pur passe-plat vers `pointblank::interrogate()` et un +n'agit que sur le chemin Arrow. Regroupement : + +```r +# NB : lang/locale montres avec les defauts ACTUELS (0.4.x, fr/fr_FR) ; +# la section 5 propose de basculer le defaut 0.5 vers en/en_US +compare_datasets( + reference, candidate, key = NULL, rules = NULL, + extract = extract_opts(failed = TRUE, first_n = NULL, sample_n = NULL, + sample_frac = NULL, limit = 5000), + engine = engine_opts(duckdb_memory_limit = "8GB"), + lang = getOption("datadiff.lang", "fr"), + locale = getOption("datadiff.locale", "fr_FR") +) +``` + +- `extract_opts()` / `engine_opts()` sont des constructeurs valides + (erreurs franches, defauts documentes en un seul endroit). +- La signature centrale descend de 17 a ~8 parametres. + +### 3. Retour : classe `datadiff_result` + +Etat actuel : `all_passed` existe en 3 exemplaires (`$all_passed`, +`$summary$all_passed`, `pointblank::all_passed($reponse)`) ; `$agent` n'est +pas interroge (et il est factice sur le fast-path all-pass) sans usage +utilisateur identifie ; `$reponse` est du franglais. + +Cible : + +```r +res$passed # le verdict, une seule fois +res$coverage # inchange +res$summary # inchange (sans all_passed duplique) +res$report # l'agent interroge (ex-$reponse), print() paresseux inchange +res$applied_rules, res$missing_in_candidate, res$extra_in_candidate +``` + +- `$reponse` et `$all_passed` restent presents une version avec un warning de + depreciation a l'acces (active binding ou methode `$.datadiff_result`). +- `$agent` est retire du contrat documente (garde interne si necessaire). + +### 4. warn_at / stop_at + +Les deux valent 1e-14 : WARN et STOP se declenchent toujours ensemble, le +niveau WARN n'apporte rien. Proposition : un unique `fail_at = 1e-14` +(fraction), les deux niveaux pointblank cales dessus ; `warn_at`/`stop_at` +acceptes par l'alias legacy avec warning si differents. + +### 5. Langue + +- Deux ecoles : (a) tout anglais par defaut (`lang = "en"`), coherent avec + les messages ; (b) statu quo francais documente. La 0.4.4 avait annonce (a) + puis un commit l'a re-bascule sans NEWS (issue #26 : la doc est desormais + alignee sur le defaut reel "fr"). +- Proposition : basculer a `"en"` au moment du passage 0.5 (major-ish), via + `getOption("datadiff.lang", "en")`, avec entree NEWS Breaking changes. + +### 6. Messages + +Uniformiser sur le style des bons warnings existants (doublons de cles, +type_mismatch : contexte + consequence + action). En particulier remplacer +`message("key is missing")` par une note explicite unique documentant le mode +positionnel, ou la supprimer (le mode positionnel est un choix legitime). + +### 7. write_rules_template() + +- 19 parametres au nommage incoherent (`na_equal_default` vs `numeric_abs`) : + harmoniser en `0.5` (`na_equal`, `numeric_abs`, ...) via l'alias. +- Ne plus ecrire par defaut `rules.yaml` dans le repertoire courant : + `path` obligatoire ou defaut `tempfile()`. +- `ref_suffix` : detail d'implementation, a retirer de la signature publique. + +## Cycle de depreciation + +1. 0.5.0 : nouvelle surface + alias retrocompatibles complets, warnings de + depreciation conditionnels (une fois par session), vignette reecrite sur la + nouvelle surface, annexe migration. +2. 0.6.0 : warnings inconditionnels. +3. 1.0.0 : retrait des alias. + +## Quick wins deja traites ou rattaches a d'autres issues + +- Precedence argument > YAML (issue #20, fait en 0.4.10). +- Validation label / key / duckdb_memory_limit (issues #16/#20/#30, fait). +- Contradictions NEWS %||% / lang / "comparaison" (issue #26). +- Parametre mort cols_reference (issue #25). +- equal_mode inerte (issue #27).