From a2ac3e399cb7230bf1ed44e444e7fd7f772c5a42 Mon Sep 17 00:00:00 2001
From: Benedikt Reinartz <filmor@gmail.com>
Date: Sun, 14 May 2023 20:27:31 +0200
Subject: [PATCH] Update documentation

---
 CHANGELOG.md |  5 +++++
 README.md    | 18 +++++++++++-------
 UPGRADE.md   | 19 +++++++++++++++++++
 3 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 81925e3f..c84ad9d5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,11 @@ See [`UPGRADE.md`](./UPGRADE.md) for additional help when upgrading to newer ver
 
 ## [unreleased]
 
+### Changed
+
+* Use Cargo features to define the NIF version level (#537), deprecating
+  `RUSTLER_NIF_VERSION`
+
 ## [0.28.0] - 2023-04-24
 
 ### Added
diff --git a/README.md b/README.md
index 07243fe2..0748d4da 100644
--- a/README.md
+++ b/README.md
@@ -57,15 +57,19 @@ Rustler aims to support the newest three major OTP versions as well as newest th
 
 #### Supported NIF version
 
-Rustler uses `erlang:system_info(nif_version)` to detect the supported NIF version of the Erlang/OTP
-system for which the NIF is to be compiled. It is possible to restrict the NIF version to an older
-version if the NIF is to be compiled for an older version of Erlang. For example, if the target NIF
-version should be `2.14` (Erlang/OTP 21), this can be defined using an environment variable:
-
-```
-RUSTLER_NIF_VERSION=2.14 mix compile
+The minimal supported NIF version for a library should be defined via Cargo
+features. The default is currently `2.14` (Erlang/OTP 21). To use features from
+NIF version `2.16` (Erlang/OTP 24), the respective feature flag has to be
+enabled on the dependency:
+
+```toml
+[dependencies]
+rustler = { version = "...", features = ["nif_version_2_16"] }
 ```
 
+For compatibility reasons, this can be defined (and overridden) by setting the
+`RUSTLER_NIF_VERSION` environment variable during build.
+
 #### Community
 
 You can find us in the `#rustler:matrix.org` channel on [Matrix](https://matrix.to/#/#rustler:matrix.org)
diff --git a/UPGRADE.md b/UPGRADE.md
index 1cfd27b0..c2192887 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -2,6 +2,25 @@
 
 This document is intended to simplify upgrading to newer versions by extending the changelog.
 
+## 0.28 -> 0.29
+
+`RUSTLER_NIF_VERSION` is deprecated and will not be considered anymore for 0.30.
+The NIF version will also not be guessed anymore from a potentially available
+installed Erlang version. By default, NIF libraries will now be compiled against
+NIF version 2.14 which is compatible down to OTP21. The default will be adjusted
+along with the supported OTP versions.
+
+If additional features are required that use newer NIF versions, these can be
+included explicitly in the project's `Cargo.toml` as, e.g.
+
+```toml
+[dependencies]
+rustler = { version = "0.30", features = ["nif_version_2_17"] }
+```
+
+With this configuration, the resulting NIF library will only work from OTP26
+onwards, but will also have access to the largest feature set.
+
 ## 0.26 -> 0.27
 
 `MIX_ENV` is no longer considered for determining the build profile. Now, the