Merge pull request conan-io#2896 from conan-io/master

Master to develop

conan_v2.rst

@@ -1,4 +1,3 @@
-.. _conan_v2:
 .. _conan2_migration_guide:
 
 

configuration/download_cache.rst

@@ -66,7 +66,7 @@ Concurrency, multiple caches and CI
 
 The downloads cache implements exclusive locks for concurrency, so it can be shared among different concurrent Conan instances.
 This is a typical scenario in CI servers, in which each job uses a different Conan package cache (defined by ``CONAN_USER_HOME`` environment
-variable). Every different Conan instance could configure its download cache to share the same storage. The download cache implements interprocess
+variable). Every different Conan instance could configure its download cache to share the same storage. The download cache implements inter-process
 exclusive locks, so only 1 process will access at a time to a given cached artifact. If other processes needs the same artifact, they will wait
 until it is released, avoiding multiple downloads of the same file, even if they were requested almost simultaneously.
 

creating_packages/define_abi_compatibility.rst

@@ -171,7 +171,8 @@ Compatible packages
 
 .. warning::
 
-    This is an **experimental** feature subject to breaking changes in future releases.
+    Some parts of this feature are **deprecated**. Please refer to the :ref:`Migration Guidelines<conan2_migration_guide>`
+    to find the feature that will carry over. The :ref:`method_compatibility` documented below is the current recommendation.
 
 The above approach defined 1 package ID for different input configurations. For example, all ``gcc`` versions
 in the range ``(v >= "4.5" and v < "5.0")`` will have exactly the same package ID, no matter what was the gcc version
@@ -244,7 +245,7 @@ Check the :ref:`Compatible Compilers<compatible_compilers>` section to see anoth
 **New conanfile.compatibility() method**
 
 The *conanfile.compatible_packages* will be substituted by the new
-:ref:`method_compatibility` experimental method in Conan 2.0. This method allows you to
+:ref:`method_compatibility` method in Conan 2.0. This method allows you to
 declare compatibility in a similar way:
 
 ..  code-block:: python
@@ -741,7 +742,7 @@ generated with the ``recipe_revision_mode`` can be resolved if no package for th
 Enabling full transitivity in package_id modes
 ++++++++++++++++++++++++++++++++++++++++++++++
 
-.. warning::
+.. attention::
 
     This will become the default behavior in the future (Conan 2.0). It is recommended to activate it when possible (it might require rebuilding some packages,
     as their package IDs will change)

creating_packages/external_repo.rst

@@ -39,7 +39,8 @@ You can also use the :ref:`tools.Git <tools_git>` class:
 
 .. warning::
 
-    This is an **experimental** feature subject to breaking changes in future releases.
+    This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines<conan2_migration_guide>`
+    to find the feature that replaces this one.
 
 .. code-block:: python
 

creating_packages/getting_started.rst

@@ -14,9 +14,10 @@ packages from sources in your computer.
     It is not strictly required by Conan to create packages, you can use
     other build systems (as VS, Meson, Autotools and even your own) to do that, without any dependency
     to CMake.
-    Some of the features used in this section are **experimental**, like ``CMakeToolchain`` or ``cmake_layout()``,
-    and they might change in future releases. There are other alternative tools that are stable, please check
-    the :ref:`reference section<references>` for more information.
+
+    Some of the features used in this section are still **under development**, like ``CMakeToolchain`` or ``cmake_layout()``,
+    while they are recommended and usable and we will try not to break them in future releases, some breaking
+    changes might still happen if necessary to prepare for the *Conan 2.0 release*.
 
 
 Using the :command:`conan new` command will create a "Hello World" C++ library example project for us:

creating_packages/package_approaches.rst

@@ -1,6 +1,12 @@
 Packaging Approaches
 ====================
 
+.. caution::
+
+    We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references
+    **deprecated** features which will not be carried forward with the new release. It's important to check the 
+    :ref:`Migration Guidelines<conan2_migration_guide>` to ensure you are using the most up to date features.
+
 Package recipes have three methods for controlling the package's binary compatibility and for implementing
 different packaging approaches: :ref:`method_package_id`, :ref:`method_build_id` and :ref:`method_package_info`.
 

creating_packages/package_information.rst

@@ -3,6 +3,12 @@
 Define the package information
 ==============================
 
+.. caution::
+
+    We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references
+    **deprecated** features which will not be carried forward with the new release. It's important to check the 
+    :ref:`Migration Guidelines<conan2_migration_guide>` to ensure you are using the most up to date features.
+
 When creating a recipe to package a library, it is important to define the information about the package so consumers can get the
 information correctly. Conan achieves this by decoupling the information of the package from the format needed using
 :ref:`generators_reference`, that translate the generic information into the appropriate format file.
@@ -21,7 +27,7 @@ like the location of the header files, library names, defines, flags...
         def package_info(self):
             self.cpp_info.includedirs = ["include/cool"]
             self.cpp_info.libs = ["libcool"]
-            self.cpp_info.defines= ["DEFINE_COOL=1"]
+            self.cpp_info.defines = ["DEFINE_COOL=1"]
 
 The package information is done using the attributes of the :ref:`cpp_info_attributes_reference` object. This information will be aggregated
 by Conan and exposed via ``self.deps_cpp_info`` to consumers and generators.
@@ -45,10 +51,6 @@ Using Components
 If your package contains more than one library or you want to define separated components so consumers can have more granular information,
 you can use components in your :ref:`method_package_info` method.
 
-.. warning::
-
-    This is a **experimental** feature subject to breaking changes in future releases.
-
 When you are creating a Conan package, it is recommended to have only one library (*.lib*, *.a*, *.so*, *.dll*...) per package. However,
 especially with third-party projects like Boost, Poco or OpenSSL, they would contain several libraries inside.
 

creating_packages/package_repo.rst

@@ -3,6 +3,12 @@
 Recipe and Sources in the Same Repo
 ===================================
 
+.. caution::
+
+    We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references
+    **deprecated** features which will not be carried forward with the new release. It's important to check the 
+    :ref:`Migration Guidelines<conan2_migration_guide>` to ensure you are using the most up to date features.
+
 Sometimes it is more convenient to have the recipe and source code together in the same repository.
 This is true especially if you are developing and packaging your own library, and not one from a third-party.
 
@@ -101,9 +107,8 @@ Capturing the Remote and Commit: ``scm``
 
 .. warning::
 
-    This is an **experimental** feature subject to breaking changes in future releases. Although this
-    is an experimental feature, the use of the feature using ``scm_to_conandata`` is considered
-    stable.
+    This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines<conan2_migration_guide>`
+    to find the feature that replaces this one.
 
 You can use the :ref:`scm attribute <scm_attribute>` with the ``url`` and ``revision`` field set to ``auto``.
 When you export the recipe (or when :command:`conan create` is called) the exported recipe will capture the

creating_packages/package_tools.rst

@@ -1,7 +1,7 @@
 .. _package_tools:
 
 Package Creator Tools
-==========================
+=====================
 
 Using Python (or just pure shell or bash) scripting, allows you to easily automate the whole package
 creation and testing process, for many different configurations. For example you could put the
@@ -33,6 +33,14 @@ This is a pure Python script, not related to Conan, and should be run as such:
 
    $ python build.py
 
+
+Conan Package Tools
+-------------------
+
+.. caution::
+
+    According to the project's README, there is no planned support for the upcoming *Conan 2.0 release*.
+
 We have developed another FOSS tool for package creators, the **Conan Package Tools** to help you generate multiple binary packages from a package recipe.
 It offers a simple way to define the different configurations and to call :command:`conan test`.
 In addition to offering CI integration like **Travis CI, Appveyor and Bamboo**, for cloud-based automated

creating_packages/toolchains.rst

@@ -1,23 +1,7 @@
 Toolchains
 ==========
 
-.. warning:
-
-    This is a very **EXPERIMENTAL** feature, introduced in Conan 1.26, with limited functionality,
-    and subject to breaking changes in the future.
-    The current goal is to gather experience and feedback
-    to evolve it, while adding more build systems.
-
-    Please try it and provide feedback at: https://github.com/conan-io/conan/issues
-
-.. warning:
-
-    Starting in Conan 1.32 ``toolchain()`` method and ``toolchain`` attribute have been
-    deprecated. They will be removed in Conan 1.33, please use ``generate()`` instead of
-    ``toolchain()`` and ``generators = "ToolChainClassName"`` instead of
-    ``toolchain`` attribute.
-
-Toolchains are the new, experimental way to integrate with build systems in Conan.
+Toolchains are the new way to integrate with build systems in Conan.
 Recipes can define a ``generate()`` method that will return an object which
 can generate files from the current configuration that can be used by the build systems.
 Conan *generators* provide information about dependencies, while toolchains provide a
@@ -38,10 +22,9 @@ For example, for using the CMake toolchain this should be declared in the recipe
 
     generators = "CMakeToolchain"
 
-.. note::
+.. tip::
 
-    At the moment (Conan 1.32), the available built-in toolchains are ``CMakeToolchain``,
-    ``MSBuildToolchain`` and ``MesonToolchain``.
+    You can explore available toolchains in the :ref:`new tools section<conan_tools>`
 
 But in the more general case, and if it needs any specific configuration beyond the default
 one:
@@ -62,7 +45,7 @@ deduced from the current configuration of ``self.settings`` and ``self.options``
 
 .. code:: python
 
-    from conans.tools import save
+    from conan.tools.files import save
 
     def generate(self):
         # Based on the self.settings, self.options, the user
@@ -104,6 +87,3 @@ the documentation of each toolchain to check the associated build helper availab
         # NOTE: This is a simplified helper
         # Not all arguments attributes and methods might be available
         cmake = CMake(self)
-
-
-To learn more about existing built-in toolchains, read the reference in :ref:`conan_tools`.

developing_packages/editable_packages.rst

@@ -6,8 +6,10 @@ Packages in editable mode
 .. important::
 
     This is a **tutorial** section. You are encouraged to execute these commands.
-    Some of the features used in this section are **experimental**, like ``layout()`` or ``CMakeToolchain``,
-    and they might change in future releases. Check the :ref:`reference section<references>` for more information.
+
+    Some of the features used in this section are still **under development**, like ``layout()`` or ``CMakeToolchain``,
+    while they are recommended and usable and we will try not to break them in future releases, some breaking
+    changes might still happen if necessary to prepare for the *Conan 2.0 release*.
 
 When working in big projects with several functionalities interconnected it is recommended to avoid
 the one-and-only huge project approach in favor of several libraries, each one specialized

developing_packages/package_layout.rst

@@ -3,9 +3,14 @@
 Package layout
 ==============
 
-.. warning::
+.. important::
+
+    Some of the features used in this section are still **under development**, while they are
+    recommended and usable and we will try not to break them in future releases, some breaking
+    changes might still happen if necessary to prepare for the *Conan 2.0 release*.
+
+.. tip::
 
-    This is an **experimental** feature subject to breaking changes in future releases.
     The ``layout()`` feature will be fully functional only in the new build system integrations
     (:ref:`in the conan.tools space <conan_tools>`). If you are using other integrations, they
     might not fully support this feature.
@@ -146,7 +151,7 @@ When we call ``conan create``, this is a simplified description of what happens:
        :caption: conanfile.py
 
        import os
-       from conans import ConanFile
+       from conan import ConanFile
        from conan.tools.cmake import CMake
 
 
@@ -273,7 +278,7 @@ Let's see how we describe our project in the ``layout()`` method:
     :caption: conanfile.py
 
     import os
-    from conans import ConanFile
+    from conan import ConanFile
     from conan.tools.cmake import CMake
 
 

devtools/build_requires.rst

@@ -95,10 +95,10 @@ profile, it will overwrite the tool requirements defined in package recipes that
 Build and Host contexts
 -----------------------
 
-.. warning::
+.. note::
 
-    This section refers to the **experimental feature** that is activated when using ``--profile:build`` and ``--profile:host``
-    in the command-line. It is currently under development, features can be added or removed in the following versions.
+    This section refers to the feature that is activated when using ``--profile:build`` and ``--profile:host``
+    in the command-line.
 
 
 Conan v1.24 differentiates between the ``build`` context and the ``host`` context in the dependency graph (read more about
@@ -269,7 +269,8 @@ same ``tool_requires`` package. Something like:
 
 .. code-block:: python
 
-    from conans import ConanFile
+    from conan import ConanFile
+
     class Pkg(ConanFile):
         python_requires ="tool/[>=0.0]"
         tool_requires ="tool/[>=0.0]"
@@ -284,11 +285,12 @@ be used to compute the ``package_id`` following the ``default_python_requires_id
 Testing tool_requires
 ----------------------
 
-.. warning::
+.. important::
 
-    This is an **experimental** feature, subject to future breaking changes
+    This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases,
+    some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*.
 
-Available since: `1.44.0 <https://github.com/conan-io/conan/releases>`_
+Available since: `1.44.0 <https://github.com/conan-io/conan/releases/tag/1.44.0>`_
 
 From Conan 1.44, it is possible to test ``tool_requires`` with the ``test_package`` functionality.
 In the ``test_package/conanfile.py``, specify the ``test_type = "explicit"`` and use the variable
@@ -297,7 +299,7 @@ as a ``tool_requires`` or ``test_requires``:
 
 .. code-block:: python
 
-    from conans import ConanFile
+    from conan import ConanFile
 
     class Pkg(ConanFile):
         test_type = "explicit"
@@ -311,7 +313,7 @@ then it is possible to specify:
 
 .. code-block:: python
 
-    from conans import ConanFile
+    from conan import ConanFile
 
     class Pkg(ConanFile):
         test_type = "explicit"

devtools/create_installer_packages.rst

@@ -3,6 +3,12 @@
 Creating conan packages to install dev tools
 ============================================
 
+.. caution::
+
+    We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references
+    **deprecated** features which will not be carried forward with the new release. It's important to check the 
+    :ref:`Migration Guidelines<conan2_migration_guide>` to ensure you are using the most up to date features.
+
 One of the most useful features of Conan is to package executables like compilers or build tools and
 distribute them in a controlled way to the team of developers. This way Conan helps not only with the
 graph of dependencies of the application itself, but also with all the ecosystem needed to generate the
@@ -82,10 +88,10 @@ This two simple declarations are enough to reuse this tool in the scenarios we a
 Using the tool packages in other recipes
 ----------------------------------------
 
-.. warning::
+.. note::
 
-    This section refers to the **experimental feature** that is activated when using ``--profile:build`` and ``--profile:host``
-    in the command-line. It is currently under development, features can be added or removed in the following versions.
+    This section refers to the feature that is activated when using ``--profile:build`` and ``--profile:host``
+    in the command-line.
 
 
 These kind of tools are not usually part of the application graph itself, they are needed only to build the library, so

devtools/running_packages.rst

@@ -3,6 +3,12 @@
 Running and deploying packages
 ==============================
 
+.. caution::
+
+    We are actively working to finalize the *Conan 2.0 Release*. Some of the information on this page references
+    **deprecated** features which will not be carried forward with the new release. It's important to check the 
+    :ref:`Migration Guidelines<conan2_migration_guide>` to ensure you are using the most up to date features.
+
 Executables and applications including shared libraries can also be distributed, deployed and run with Conan. This might have
 some advantages compared to deploying with other systems:
 

extending/python_requires.rst

@@ -3,9 +3,10 @@
 Python requires
 ===============
 
-.. warning::
+.. important::
 
-    This is an **experimental** feature subject to breaking changes in future releases.
+    This feature is still **under development**, while it is recommended and usable and we will try not to break them in future releases,
+    some breaking changes might still happen if necessary to prepare for the *Conan 2.0 release*.
 
 
 .. note::

extending/python_requires_legacy.rst

@@ -5,9 +5,13 @@ Python requires (legacy)
 
 .. warning::
 
-    This feature has been superseded by the new :ref:`python_requires`. Even if this is an **experimental**
-    feature subject to breaking changes in future releases, this legacy ``python_requires`` syntax has not
-    been removed yet, but it will be removed in Conan 2.0.
+
+    This is a **deprecated** feature by the new :ref:`python_requires`. Please refer to the :ref:`Migration Guidelines<conan2_migration_guide>`
+    to find the feature that replaced this one.
+
+    The new, **under development** While they are
+    recommended and usable and we will try not to break them in future releases, some breaking
+    changes might still happen if necessary to prepare for the *Conan 2.0 release*.
 
 The ``python_requires()`` feature is a very convenient way to share files and code between
 different recipes. A *Python Requires* is just like any other recipe, it is the way it is