[R] Allow controlling strict mode through env. variable (dmlc#11254)

Author: david-cortes

R-package/R/utils.R

@@ -540,11 +540,24 @@ NULL
 #'
 #' Currently, the only supported option is `xgboost.strict_mode`, which can be set to `TRUE` or
 #' `FALSE` (default).
+#'
+#' In addition to an R option, it can also be enabled through by setting environment variable
+#' `XGB_STRICT_MODE=1`. If set, this environment variable will take precedence over the option.
 #' @examples
 #' options("xgboost.strict_mode" = FALSE)
 #' options("xgboost.strict_mode" = TRUE)
+#' Sys.setenv("XGB_STRICT_MODE" = "1")
+#' Sys.setenv("XGB_STRICT_MODE" = "0")
 NULL
 
+get.strict.mode.option <- function() {
+  env_var_option <- Sys.getenv("XGB_STRICT_MODE")
+  if (!nchar(env_var_option)) {
+    return(getOption("xgboost.strict_mode", default = FALSE))
+  }
+  return(tolower(as.character(env_var_option)) %in% c("1", "true", "t", "yes", "y"))
+}
+
 # Lookup table for the deprecated parameters bookkeeping
 deprecated_train_params <- list(
   renamed = list(
@@ -639,7 +652,7 @@ check.deprecation <- function(
   if (length(params) == 0) {
     return(NULL)
   }
-  error_on_deprecated <- getOption("xgboost.strict_mode", default = FALSE)
+  error_on_deprecated <- get.strict.mode.option()
   throw_err_or_depr_msg <- function(...) {
     if (error_on_deprecated) {
       stop(...)

R-package/man/xgboost-options.Rd

@@ -44,3 +44,22 @@ XGBoost's R language bindings had large breaking changes between versions 1.x an
         - R-side attributes (which can be accessed and modified through R function ``attributes(model)`` and ``attributes(model)$field <- val``), which allow arbitrary objects. Many attributes are automatically added by the model building functions, such as evaluation logs (a ``data.table`` with metrics calculated per iteration), which previously were model fields.
         - C-level attributes, which allow only JSON-compliant data and which can be accessed and set through function ``xgb.attributes(model)``. These C-level attributes are shareable through serialized models in different XGBoost interfaces, while the R-level ones are specific to the R interface. Some attributes that are standard among language bindings of XGBoost, such as the best interation, are kept as C attributes.
     - Previously, models that were just de-serialized from an on-disk format required calling method 'xgb.Booster.complete' on them to finish the full de-serialization process before being usable, or would otherwise call this method on their own automatically automatically at the first call to 'predict'. Serialization is now handled more gracefully, and there are no additional functions/methods involved - i.e. if one saves a model to disk with ``saveRDS()`` and then reads it back with ``readRDS()``, the model will be fully loaded straight away, without needing to call additional methods on it.
+
+Other recommendations
+---------------------
+
+By default, XGBoost might recognize that some parameter has been removed or renamed from how it was in a previous version, and still accept the same function call as it used to do before with the renamed or removed arugments, but issuing a deprecation warning along the way that highlights the changes.
+
+These behaviors will be removed in future versions, and function calls which currently return deprecation warnings will stop working in the future, so in order to make sure that code calling XGBoost will still keep working, it should be ensured that it doesn't issue deprecation warnings.
+
+Optionally, these deprecation warnings can be turned into errors (while still keeping other types of warnings as warnings) through an option "xgboost.strict_mode" - example:
+.. code-block:: r
+
+    options("xgboost.strict_mode" = TRUE)
+
+It can also be controlled through an environment variable `XGB_STRICT_MODE=1`, which takes precende over the R option - e.g.:
+.. code-block:: r
+
+    Sys.setenv("XGB_STRICT_MODE" = "1")
+
+It is highly recommended for package developers to enable this option during their package checks to ensure better compatibility with XGBoost.