From 0fd9c0da8f3d830d115f7034102f74038f63aefb Mon Sep 17 00:00:00 2001 From: Quemuel Baruque Date: Tue, 20 Oct 2026 10:30:33 -0300 Subject: [PATCH] fix: align deprecation warnings with transition policy --- NEWS.md | 5 ++- R/api.R | 8 +++- docs/refactoring/api-migration.md | 28 ++++++------- tests/testthat/test-api.R | 65 +++++++++++++------------------ 4 files changed, 52 insertions(+), 54 deletions(-) diff --git a/NEWS.md b/NEWS.md index 7661ee0..03c0a96 100644 --- a/NEWS.md +++ b/NEWS.md @@ -36,8 +36,9 @@ - Added focused readers and computational names including `fetch_cases()`, `fetch_case_records()`, `fetch_climate()`, `estimate_rt()`, `nowcast_cases()`, `define_alert_rules()`, and `classify_alerts()`. -- Legacy counterparts remain available as thin wrappers and emit staged - deprecation warnings through `lifecycle`. +- Legacy counterparts remain available as thin wrappers. Per the approved + transition policy, `lifecycle` deprecation warnings begin in version 1.3.0; + version 1.2.0 does not warn ahead of that transition. - Added `upsert_alert_parameters()` for transactional parameter batches and a migration table documenting functions, arguments, schemas, and intentional differences. diff --git a/R/api.R b/R/api.R index c13db9c..06add0d 100644 --- a/R/api.R +++ b/R/api.R @@ -468,7 +468,13 @@ classify_alerts <- function(data, rules, missing = FALSE, minimum_history = 8) { # Legacy wrappers ------------------------------------------------------------ .deprecate_api <- function(old, replacement) { - lifecycle::deprecate_warn("1.1.0", old, replacement, user_env = parent.frame(2L)) + warning_start <- package_version("1.3.0") + package_version <- utils::packageVersion("AlertTools") + if (package_version >= warning_start) { + lifecycle::deprecate_warn("1.3.0", old, replacement, + user_env = parent.frame(2L)) + } + invisible(NULL) } #' Legacy Rt estimator diff --git a/docs/refactoring/api-migration.md b/docs/refactoring/api-migration.md index 8e443af..8a5c4b5 100644 --- a/docs/refactoring/api-migration.md +++ b/docs/refactoring/api-migration.md @@ -1,6 +1,8 @@ # Migração para a API `snake_case` -Versão de início da depreciação: 1.1.0. +Versão de início dos avisos formais de depreciação: 1.3.0, conforme +`transition-policy.dcf`. Na versão 1.2.0, os wrappers continuam disponíveis sem +antecipar esses avisos. A API nova separa leitura, cálculo e persistência. Funções experimentais estão identificadas na ajuda do pacote e podem receber ajustes compatíveis antes de @@ -26,18 +28,18 @@ suporte ainda está proposta; nenhuma data de remoção foi aprovada. | API legada | API nova | Adaptação principal | Situação | |---|---|---|---| -| `getCases()` | `fetch_cases()` | `datasource` → `conn`; `cities` → `geocodes`; `cid10` → `disease`; `firstday`/`lastday` → `start_date`/`end_date`; `dataini` → `case_date` | wrapper depreciado desde 1.1.0 | -| `getCaseslist()` | `fetch_case_records()` | mesmos argumentos de conexão, local, doença e datas | wrapper depreciado desde 1.1.0 | -| `getClima()` | `fetch_climate()` | `vars` → `climate_vars`; datas explícitas | wrapper depreciado desde 1.1.0 | -| `read.parameters()` | `fetch_alert_parameters()` | `datasource` → `conn`; `cities` → `geocodes`; nomes de doenças aceitos | wrapper depreciado desde 1.1.0 | -| `pipe_infodengue()` | `fetch_alert_inputs()` + `run_alert_pipeline()` | leitura e cálculo passam a ser chamadas separadas; escrita removida do cálculo | wrapper depreciado desde 1.1.0 | -| `Rt()` | `estimate_rt()` | argumentos longos em `snake_case` | wrapper depreciado desde 1.1.0 | -| `adjustIncidence()` | `nowcast_cases()` | `datas` → `case_records`; `nowSE` → `report_week` | wrapper depreciado desde 1.1.0 | -| `setCriteria()` | `define_alert_rules()` | `delays` preservado | wrapper depreciado desde 1.1.0 | -| `fouralert()` | `classify_alerts()` | `crit` → `rules`; `miss` → `missing`; `dy` → `minimum_history` | wrapper depreciado desde 1.1.0 | -| `tabela_historico()` | `as_alert_history()` | `versao` → `version_date`; `iniSE`/`lastSE` → `start_week`/`end_week` | wrapper depreciado desde 1.1.0 | -| `write_alerta()` | `write_alert_results()` | recebe diretamente `alerttools_result`; não exporta arquivo implicitamente | wrapper depreciado desde 1.1.0 | -| `write_parameters()` | `upsert_alert_parameters()` | aceita lote; `overwrite` é substituído por `conflict` | wrapper depreciado desde 1.1.0 | +| `getCases()` | `fetch_cases()` | `datasource` → `conn`; `cities` → `geocodes`; `cid10` → `disease`; `firstday`/`lastday` → `start_date`/`end_date`; `dataini` → `case_date` | aviso a partir de 1.3.0 | +| `getCaseslist()` | `fetch_case_records()` | mesmos argumentos de conexão, local, doença e datas | aviso a partir de 1.3.0 | +| `getClima()` | `fetch_climate()` | `vars` → `climate_vars`; datas explícitas | aviso a partir de 1.3.0 | +| `read.parameters()` | `fetch_alert_parameters()` | `datasource` → `conn`; `cities` → `geocodes`; nomes de doenças aceitos | aviso a partir de 1.3.0 | +| `pipe_infodengue()` | `fetch_alert_inputs()` + `run_alert_pipeline()` | leitura e cálculo passam a ser chamadas separadas; escrita removida do cálculo | aviso a partir de 1.3.0 | +| `Rt()` | `estimate_rt()` | argumentos longos em `snake_case` | aviso a partir de 1.3.0 | +| `adjustIncidence()` | `nowcast_cases()` | `datas` → `case_records`; `nowSE` → `report_week` | aviso a partir de 1.3.0 | +| `setCriteria()` | `define_alert_rules()` | `delays` preservado | aviso a partir de 1.3.0 | +| `fouralert()` | `classify_alerts()` | `crit` → `rules`; `miss` → `missing`; `dy` → `minimum_history` | aviso a partir de 1.3.0 | +| `tabela_historico()` | `as_alert_history()` | `versao` → `version_date`; `iniSE`/`lastSE` → `start_week`/`end_week` | aviso a partir de 1.3.0 | +| `write_alerta()` | `write_alert_results()` | recebe diretamente `alerttools_result`; não exporta arquivo implicitamente | aviso a partir de 1.3.0 | +| `write_parameters()` | `upsert_alert_parameters()` | aceita lote; `overwrite` é substituído por `conflict` | aviso a partir de 1.3.0 | As demais funções legadas permanecem estáveis nesta fase porque não são necessárias ao fluxo mínimo comprovado. Novos nomes somente serão adicionados diff --git a/tests/testthat/test-api.R b/tests/testthat/test-api.R index e23898c..d1c0e1c 100644 --- a/tests/testthat/test-api.R +++ b/tests/testthat/test-api.R @@ -86,9 +86,8 @@ test_that("new persistence API writes results and parameters explicitly", { withr::local_options(list(lifecycle_verbosity = "warning")) history <- as_alert_history(result, as.Date("2026-09-04")) - expect_warning( - write_alerta(history, datasource = connection, conflict = "update"), - "write_alert_results" + expect_no_warning( + write_alerta(history, datasource = connection, conflict = "update") ) changed <- transform(parameter_fixture(), limiar_preseason = 23) @@ -96,7 +95,7 @@ test_that("new persistence API writes results and parameters explicitly", { expect_equal(persisted$limiar_preseason, 23) }) -test_that("legacy wrappers warn and preserve argument and result adapters", { +test_that("legacy wrappers preserve adapters without warning before 1.3.0", { withr::local_options(list(lifecycle_verbosity = "warning")) connection <- sqlite_fixture_connection(environment()) @@ -104,32 +103,29 @@ test_that("legacy wrappers warn and preserve argument and result adapters", { connection, 3304557, "dengue", as.Date("2020-12-20"), as.Date("2021-01-09") ) - expect_warning( + expect_no_warning( legacy_cases <- getCases( cities = 3304557, cid10 = "A90", firstday = as.Date("2020-12-20"), lastday = as.Date("2021-01-09"), dataini = "notific", datasource = connection - ), - "fetch_cases" + ) ) expect_identical(legacy_cases, modern_cases) - expect_warning( + expect_no_warning( legacy_records <- getCaseslist( 3304557, firstday = as.Date("2020-12-20"), lastday = as.Date("2021-01-09"), datasource = connection - ), - "fetch_case_records" + ) ) expect_identical( legacy_records, fetch_case_records(connection, 3304557, start_date = as.Date("2020-12-20"), end_date = as.Date("2021-01-09")) ) - expect_warning( + expect_no_warning( legacy_climate <- getClima( 3304557, vars = c("temp_min", "temp_max"), iniSE = 202052, finalday = as.Date("2021-01-02"), datasource = connection - ), - "fetch_climate" + ) ) expect_identical( legacy_climate, @@ -138,22 +134,19 @@ test_that("legacy wrappers warn and preserve argument and result adapters", { ) modern_parameters <- fetch_alert_parameters(connection, 3304557, "dengue") - expect_warning( - legacy_parameters <- read.parameters(3304557, cid10 = "A90", datasource = connection), - "fetch_alert_parameters" + expect_no_warning( + legacy_parameters <- read.parameters(3304557, cid10 = "A90", datasource = connection) ) expect_identical(legacy_parameters, modern_parameters) - expect_warning( + expect_no_warning( write_parameters(3304557, "A90", modern_parameters, overwrite = TRUE, - datasource = connection), - "upsert_alert_parameters" + datasource = connection) ) - expect_warning( - expect_error( - pipe_infodengue(3304557, datarelatorio = 202101, datasource = NULL), - "valid DBI connection" + expect_error( + expect_no_warning( + pipe_infodengue(3304557, datarelatorio = 202101, datasource = NULL) ), - "run_alert_pipeline" + "valid DBI connection" ) }) @@ -208,7 +201,7 @@ test_that("snake_case computational aliases preserve baseline results", { expect_identical(rules, setCriteria("Af", criteria_values)) }) -test_that("legacy computational wrappers identify replacements and remain equivalent", { +test_that("legacy computational wrappers remain equivalent without early warnings", { withr::local_options(list(lifecycle_verbosity = "warning")) cases <- read_fixture("cases.csv") climate <- read_fixture("climate.csv") @@ -216,22 +209,20 @@ test_that("legacy computational wrappers identify replacements and remain equiva modern_rt <- estimate_rt(cases, count = "casos", distribution = "normal", mean_generation_time = 3, sd_generation_time = 1) - expect_warning( - legacy_rt <- Rt(cases, count = "casos", gtdist = "normal", meangt = 3, sdgt = 1), - "estimate_rt" + expect_no_warning( + legacy_rt <- Rt(cases, count = "casos", gtdist = "normal", meangt = 3, sdgt = 1) ) expect_identical(legacy_rt, modern_rt) modern_nowcast <- nowcast_cases(cases, method = "none", report_week = 202106) - expect_warning( - legacy_nowcast <- adjustIncidence(cases, method = "none", nowSE = 202106), - "nowcast_cases" + expect_no_warning( + legacy_nowcast <- adjustIncidence(cases, method = "none", nowSE = 202106) ) expect_identical(legacy_nowcast, modern_nowcast) values <- structure(as.character(parameters[1, ]), names = names(parameters)) modern_rules <- define_alert_rules("Af", values) - expect_warning(legacy_rules <- setCriteria("Af", values), "define_alert_rules") + expect_no_warning(legacy_rules <- setCriteria("Af", values)) expect_identical(legacy_rules, modern_rules) result <- run_alert_pipeline( @@ -240,15 +231,13 @@ test_that("legacy computational wrappers identify replacements and remain equiva ) modern_alert <- classify_alerts(result$data, modern_rules, missing = "last", minimum_history = 4) - expect_warning( - legacy_alert <- fouralert(result$data, modern_rules, miss = "last", dy = 4), - "classify_alerts" + expect_no_warning( + legacy_alert <- fouralert(result$data, modern_rules, miss = "last", dy = 4) ) expect_identical(legacy_alert, modern_alert) modern_history <- as_alert_history(result, as.Date("2026-09-04")) - expect_warning( - legacy_history <- tabela_historico(result, versao = as.Date("2026-09-04")), - "as_alert_history" + expect_no_warning( + legacy_history <- tabela_historico(result, versao = as.Date("2026-09-04")) ) expect_identical(legacy_history, modern_history) })