Properly mark things that are deprecated as deprecated (#1562)

Properly mark things that are deprecated as deprecated and add a new environment variable called REZ_LOG_DEPRECATION_WARNINGS to help users know when they are using deprecated things.

---------

Signed-off-by: Jean-Christophe Morin <jean_christophe_morin@hotmail.com>

CHANGELOG.md

@@ -1,4 +1,78 @@
-# Change Log
+# Change log
+
+<!-- start-here-sphinx-start-after -->
+
+## 2.114.0 (TBD)
+
+Probably the last release before 3.0.0
+
+Rez installations now only support Python 3.7+. It is important to note that the API
+can still be used with Python 2.7+ but this will be dropped in 3.0.0
+
+### Features
+
+* New environment variable `REZ_LOG_DEPRECATION_WARNINGS` that will force
+  all deprecation warnings to be printed, ignoring `PYTHONWARNINGS` and custom
+  warning filters. Note that enabling this will forcefully load every
+  configuration file instead of loading them lazilly.
+
+### Deprecations
+
+We decided to deprecated some things that have been "deprecated" for a while but were never
+officially marked as deprecated. We have prepared
+[a guide](https://rez.readthedocs.io/en/stable/guides/prepare_for_3.html)
+to help you navigate these deprecations.
+
+What follows is everything that is marked as deprecated with information on when
+removal will happen or when defaults will change.
+
+- Configuration settings:
+  - [disable_rez_1_compatibility](https://rez.readthedocs.io/en/stable/configuring_rez.html#disable_rez_1_compatibility):
+    Will be removed in a yet to be determined future release.
+  - [debug_old_commands](https://rez.readthedocs.io/en/stable/configuring_rez.html#debug_old_commands):
+    Will be removed in 3.0.0. This setting is currently a no-op.
+  - [warn_old_commands](https://rez.readthedocs.io/en/stable/configuring_rez.html#warn_old_commands):
+    Will be removed in a yet to be determined future release.
+  - [error_old_commands](https://rez.readthedocs.io/en/stable/configuring_rez.html#error_old_commands):
+    Will be removed in a yet to be determined future release.
+  - [warn_commands2](https://rez.readthedocs.io/en/stable/configuring_rez.html#warn_commands2):
+    Will be removed in 3.0.0. This setting is currently a no-op.
+  - [error_commands2](https://rez.readthedocs.io/en/stable/configuring_rez.html#error_commands2):
+    Will be removed in 3.0.0. This setting is currently a no-op.
+  - [rez_1_cmake_variables](https://rez.readthedocs.io/en/stable/configuring_rez.html#rez_1_cmake_variables):
+    Will be removed in 3.0.0.
+  - [rez_1_environment_variables](https://rez.readthedocs.io/en/stable/configuring_rez.html#rez_1_environment_variables):
+    Will be removed in a yet to be determined future release.
+  - [rxt_as_yaml](https://rez.readthedocs.io/en/stable/configuring_rez.html#rxt_as_yaml):
+    Will be removed in 3.0.0.
+- Modules:
+  - `rez.vendor.version`. Use `rez.version` instead. Will be removed in 3.0.0.
+  - `rez.packages_maker__`. Use `rez.packages_maker` instead. Will be removed in 3.0.0.
+  - `rez.package_resources_`. Use `rez.package_resources` instead. Will be removed in 3.0.0.
+  - `rez.packages_`. Use `rez.packages` instead. Will be removed in 3.0.0.
+- CLI:
+  - rez-pip: The `--pip-version` argument is deprecated. Will be removed in 3.0.0.
+  - rez-search: The `--sort` argument is deprecated and has been a no-op for a while now. Will be removed in 3.0.0.
+- API:
+  - The `isolate` keyword argument of the `rez.rex.RexExecutor.execute_code` method is now officially deprecated and will be removed in 3.0.0.
+    Instead of `executor.execute_code(..., isolate=True)`, use
+    ```python
+    with executor.reset_globals():
+        executor.execute_code(...)
+    ```
+- Python: rez 3.0.0 will completely drop support for installing and using the rez API with Python 2.
+
+### Change of default values due to deprecations
+
+Some default values have changed:
+
+- [rez_1_cmake_variables](https://rez.readthedocs.io/en/stable/configuring_rez.html#rez_1_cmake_variables)
+  is now disabled by default.
+
+Some default values will change in 3.0.0:
+
+- [disable_rez_1_compatibility](https://rez.readthedocs.io/en/stable/configuring_rez.html#disable_rez_1_compatibility) will become enabled by default.
+- [rez_1_environment_variables](https://rez.readthedocs.io/en/stable/configuring_rez.html#rez_1_environment_variables) will become disabled by default.
 
 ## 2.113.0 (2023-09-11)
 [Source](https://github.com/AcademySoftwareFoundation/rez/tree/2.113.0) | [Diff](https://github.com/AcademySoftwareFoundation/rez/compare/2.112.0...2.113.0)
@@ -2257,62 +2331,62 @@ be on the lookout for unintended side effects and report them if they arise.
 
 ## 2.26.4 [[#562](https://github.com/AcademySoftwareFoundation/rez/pull/562)] Fixed Regression in 2.24.0
 
-#### Addressed Issues
+### Addressed Issues
 
 * [#561](https://github.com/AcademySoftwareFoundation/rez/issues/561) timestamp not written to installed package
 
 
 ## 2.26.3 [[#560](https://github.com/AcademySoftwareFoundation/rez/pull/560)] Package.py permissions issue
 
-#### Addressed Issues
+### Addressed Issues
 
 * [#559](https://github.com/AcademySoftwareFoundation/rez/issues/559) package.py permissions issue
 
-#### Notes
+### Notes
 
 Fixes issue where installed `package.py` can be set to r/w for only the current user.
 
 
 ## 2.26.2 [[#557](https://github.com/AcademySoftwareFoundation/rez/pull/557)] Package Copy Fixes For Non-Varianted Packages
 
-#### Addressed Issues
+### Addressed Issues
 
 * [#556](https://github.com/AcademySoftwareFoundation/rez/issues/556) rez-cp briefly copies original package definition in non-varianted packages
 * [#555](https://github.com/AcademySoftwareFoundation/rez/issues/555) rez-cp inconsistent symlinking when --shallow=true
 * [#554](https://github.com/AcademySoftwareFoundation/rez/issues/554) rez-cp doesn't keep file metadata in some cases
 
-#### Notes
+### Notes
 
 There were various minor issues related to copying non-varianted packages.
 
 
 ## 2.26.1 [[#552](https://github.com/AcademySoftwareFoundation/rez/pull/552)] Bugfix in Package Copy
 
-#### Addressed Issues
+### Addressed Issues
 
 * [#551](https://github.com/AcademySoftwareFoundation/rez/issues/551) package copy fails if symlinks in root dir
 
-#### Notes
+### Notes
 
 This was failing when symlinks were present within a non-varianted package being copied. Now, these
 symlinks are retained in the target package, unless `--follow-symlinks` is specified.
 
 
 ## 2.26.0 [[#550](https://github.com/AcademySoftwareFoundation/rez/pull/550)] Build System Detection Fixes
 
-#### Addressed Issues
+### Addressed Issues
 
 * [#549](https://github.com/AcademySoftwareFoundation/rez/issues/549) '--build-system' rez-build option not always
   available
 
-#### Notes
+### Notes
 
 To fix this issue:
 * The '--build-system' rez-build option is now always present.
 * To provide further control over the build system type, the package itself can now specify its build
   system - see https://github.com/AcademySoftwareFoundation/rez/wiki/Package-Definition-Guide#build_system
 
-#### COMPATIBILITY ISSUE!
+### COMPATIBILITY ISSUE!
 
 Unfortunately, the 'cmake' build system had its own '--build-system' commandline option also. This
 was possible because previous rez versions suppressed the standard '--build-system' option if only
@@ -2322,15 +2396,15 @@ changed to '--cmake-build-system'**.
 
 ## 2.25.0 [[#548](https://github.com/AcademySoftwareFoundation/rez/pull/548)] Various Build-related issues
 
-#### Addressed Issues
+### Addressed Issues
 
 * [#433](https://github.com/AcademySoftwareFoundation/rez/issues/433): "package_definition_build_python_paths" defined
   paths are not available from top level in package.py
 * [#442](https://github.com/AcademySoftwareFoundation/rez/issues/442): "rez-depends" and "private_build_requires"
 * [#416](https://github.com/AcademySoftwareFoundation/rez/issues/416): Need currently-building-variant build variables
 * [#547](https://github.com/AcademySoftwareFoundation/rez/issues/547): rez-cp follows symlinks within package payload
 
-#### Notes
+### Notes
 
 The biggest update in this release is the introduction of new variables accessible at early-bind time:
 building, build_variant_index and build_variant_requires. This allows you to do things like define
@@ -2361,13 +2435,13 @@ intact - but hte previous behavior can still be accessed with the rez-cp --follo
 This release adds a new tool, rez-cp, for copying packages/variants from one package repository to
 another, with optional renaming/reversioning. The associated API can be found in src/package_copy.py.
 
-#### Addressed Issues
+### Addressed Issues
 
 * #541
 * #510
 * #477
 
-#### Notes
+### Notes
 
 * Package definition file writes are now atomic;
 * private_build_requires is kept in installed/released packages;
@@ -2377,22 +2451,22 @@ another, with optional renaming/reversioning. The associated API can be found in
 
 ## 2.23.1: Fixed Regression in 2.20.0
 
-#### Addressed Issues
+### Addressed Issues
 
 * #532
 
-#### Notes
+### Notes
 
 Bug was introduced in: https://github.com/AcademySoftwareFoundation/rez/releases/tag/2.20.0
 
 
 ## 2.23.0: Package Usage Tracking, Better Config Overrides
 
-#### Addressed Issues
+### Addressed Issues
 
 * #528
 
-#### Notes
+### Notes
 
 Two new features are added in this release:
 
@@ -2411,7 +2485,7 @@ The embedded simplejson lib was removed. The native json lib is used instead, an
 
 ## 2.22.1: Stdin-related fixes
 
-#### Addressed Issues
+### Addressed Issues
 
 * #512
 * #526
@@ -2421,7 +2495,7 @@ The embedded simplejson lib was removed. The native json lib is used instead, an
 
 PR: #213
 
-#### Notes
+### Notes
 
 Package/variant/family search API is now available in package_search.py. This gives the same
 functionality as provided by the rez-search CLI tool.
@@ -2434,13 +2508,13 @@ PR: #501
 
 ## 2.20.1: Windows Fixes
 
-#### Merged PRs
+### Merged PRs
 
 * #490: Fix alias command in Windows when PATH is modified
 * #489: Fix cmd.exe not escaping special characters
 * #482: Fix selftest getting stuck on Windows
 
-#### Addressed Issues
+### Addressed Issues
 
 * #389
 * #343
@@ -2452,11 +2526,11 @@ PR: #501
 
 PR: #523
 
-#### Addressed Issues
+### Addressed Issues
 
 * #492
 
-#### Notes
+### Notes
 
 The rez-python command now supports all native python args and passes those through to its python
 subprocess - so you can now shebang with rez-python if that is useful.
@@ -2468,15 +2542,15 @@ extraneous args after -- tokens.
 
 ## 2.19.1: Fixed bug with rez-build and package preprocess
 
-#### Merged PRs
+### Merged PRs
 
 * #522
 
-#### Addressed Issues
+### Addressed Issues
 
 * #514
 
-#### Notes
+### Notes
 
 The problem occurred because the preprocess function was attempting to be serialized when the package
 definition is cached to memcache. However, this function is stripped in installed packages;

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx >=7.0.0,<8.0.0
 furo
 sphinx-autobuild
+myst-parser

docs/source/changelog.md

@@ -0,0 +1,5 @@
+# Changelog
+
+```{include} ../../CHANGELOG.md
+:start-after: <!-- start-here-sphinx-start-after -->
+```

docs/source/conf.py

@@ -37,6 +37,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
+    "myst_parser",
     # Rez custom extension
     'rez_sphinxext'
 ]

docs/source/environment.rst

@@ -252,9 +252,22 @@ operation of rez.
    Path to a file that will be consumed by :func:`logging.config.fileConfig` to configure
    the logger.
 
+
 Development Environment Variables
 =================================
 
+.. envvar:: REZ_LOG_DEPRECATION_WARNINGS
+
+   Enable all deprecation warnings to be logged regardless of how you have configured
+   your python interpreter. This is usefull to help upgrading to newer versions of rez.
+   Prior to updating, you should set this environment variable to see if you need to
+   change some things to be compatible with newer versions.
+
+   .. warning::
+
+      Enabling this will forcefully load every configuration file instead of loading them
+      lazilly. This can have an impact on startup time.
+
 .. envvar:: REZ_SIGUSR1_ACTION
 
    If you set this to ``print_stack``, rez will prints its

docs/source/guides/index.rst

@@ -0,0 +1,10 @@
+===========
+User guides
+===========
+
+This section contains various user guides.
+
+.. toctree::
+   :maxdepth: 1
+
+   prepare_for_3