Docs about 'scm_to_conandata'

creating_packages/package_repo.rst

@@ -108,44 +108,58 @@ When you export the recipe (or when :command:`conan create` is called) the expor
 remote and commit of the local repository:
 
 .. code-block:: python
-   :emphasize-lines: 7, 8
+   :emphasize-lines: 8-10
 
+    import os
     from conans import ConanFile, CMake, tools
 
     class HelloConan(ConanFile):
          scm = {
             "type": "git",  # Use "type": "svn", if local repo is managed using SVN
             "subfolder": "hello",
             "url": "auto",
-            "revision": "auto"
+            "revision": "auto",
+            "password": os.environ.get("SECRET", None)
          }
         ...
 
 You can commit and push the *conanfile.py* to your origin repository, which will always preserve the ``auto``
-values. But when the file is exported to the Conan local cache (except you have uncommitted changes, read below),
-the copied recipe in the local cache will point to the captured remote and commit:
-
-.. code-block:: python
-   :emphasize-lines: 7, 8
-
-    from conans import ConanFile, CMake, tools
-
-    class HelloConan(ConanFile):
-         scm = {
-            "type": "git",
-            "subfolder": "hello",
-            "url": "https://github.com/conan-io/hello.git",
-            "revision": "437676e15da7090a1368255097f51b1a470905a0"
-         }
-        ...
-
-So when you :ref:`upload the recipe <uploading_packages>` to a Conan remote, the recipe will contain
-the "resolved" URL and commit.
-
-When you are requiring your ``HelloConan``, the :command:`conan install` will retrieve the recipe from the
-remote. If you are building the package, the source code will be fetched from the captured url/commit.
-
-As SCM attributes are evaluated in the workspace context (see :ref:`scm attribute <scm_attribute>`),
+values. When the file is exported to the Conan local cache (except you have uncommitted changes, read below),
+these data will be stored in the *conanfile.py* itself (Conan will modify the file) or in a special file
+:ref:`conandata_yml` that will be stored together with the recipe, depending on the value of the configuration
+parameter :ref:`scm_to_conandata<conan_conf>`.
+
+ * If the ``scm_to_conandata`` is not activated (default behavior in Conan v1.x) Conan will store a modified
+   version of the *conanfile.py* with the values of the fields in plain text:
+
+   .. code-block:: python
+    :emphasize-lines: 8-10
+
+        import os
+        from conans import ConanFile, CMake, tools
+
+        class HelloConan(ConanFile):
+            scm = {
+                "type": "git",
+                "subfolder": "hello",
+                "url": "https://github.com/conan-io/hello.git",
+                "revision": "437676e15da7090a1368255097f51b1a470905a0",
+                "password": "MY_SECRET"
+            }
+            ...
+
+   So when you :ref:`upload the recipe <uploading_packages>` to a Conan remote, the recipe will contain
+   the "resolved" URL and commit.
+
+ * If ``scm_to_conandata`` is activated, the value of these fields (except ``username`` and ``password``) will
+   be stored in the :ref:`conandata_yml` file that will be automatically exported with the recipe.
+
+Whichever option you choose, the data resolved will be asigned by Conan to the corresponding field when the recipe
+file is loaded, and they will be available for all the methods defined in the recipe. Also, if building the package
+from sources, Conan will fetch the code in the captured url/commit before running the method ``source()`` in the
+recipe (if defined).
+
+As SCM attributes are evaluated in the local directory context (see :ref:`scm attribute <scm_attribute>`),
 you can write more complex functions to retrieve the proper values, this source *conanfile.py* will
 be valid too:
 

reference/conanfile/attributes.rst

@@ -1187,12 +1187,21 @@ Used to clone/checkout a repository. It is a dictionary with the following possi
    - ``shallow``: Will sync the git submodules using ``submodule sync``
    - ``recursive``: Will sync the git submodules using ``submodule sync --recursive``
 
-SCM attributes are evaluated in the workspace context where the *conanfile.py* is located before
+SCM attributes are evaluated in the working directory where the *conanfile.py* is located before
 exporting it to the Conan cache, so these values can be returned from arbitrary functions that
-depend on the workspace layout. Nevertheless, all the other code in the recipe must be able to
+depend on the local directory. Nevertheless, all the other code in the recipe must be able to
 run in the export folder inside the cache, where it has access only to the files exported (see
-attribute :ref:`exports <exports_attribute>`) and to any other functionality
-from a :ref:`python_requires <python_requires>`.
+attribute :ref:`exports <exports_attribute>` and :ref:`conandata_yml`) and to any other functionality
+from a :ref:`python_requires <python_requires>` package.
+
+.. warning::
+
+    By default, in Conan v1.x the information after evaluating the attribute ``scm`` will be stored in the
+    *conanfile.py* file (the recipe will be modified when exported to the Conan cache) and any value will be
+    written in plain text (watch out about passwords).
+    However, you can activate the :ref:`scm_to_conandata<conan_conf>` config option, the *conanfile.py*
+    won't be modified (data is stored in a different file) and the fields ``username`` and ``password`` won't be
+    stored, so these one will be computed each time the recipe is loaded.
 
 .. note::
 

reference/config_files/conan.conf.rst

@@ -39,8 +39,8 @@ The typical location of the **conan.conf** file is the directory ``~/.conan/``:
     # conan_cmake_program = cmake         # environment CONAN_CMAKE_PROGRAM (overrides the make program used in CMake.cmake_program)
 
     # cmake_generator                     # environment CONAN_CMAKE_GENERATOR
-    # https://vtk.org/Wiki/CMake_Cross_Compiling
     # cmake_generator_platform            # environment CONAN_CMAKE_GENERATOR_PLATFORM
+    # http://www.vtk.org/Wiki/CMake_Cross_Compiling
     # cmake_toolchain_file                # environment CONAN_CMAKE_TOOLCHAIN_FILE
     # cmake_system_name                   # environment CONAN_CMAKE_SYSTEM_NAME
     # cmake_system_version                # environment CONAN_CMAKE_SYSTEM_VERSION
@@ -59,6 +59,7 @@ The typical location of the **conan.conf** file is the directory ``~/.conan/``:
     # temp_test_folder = True             # environment CONAN_TEMP_TEST_FOLDER
 
     # cacert_path                         # environment CONAN_CACERT_PATH
+    # scm_to_conandata                    # environment CONAN_SCM_TO_CONANDATA
 
     [storage]
     # This is the default path, but you can write your own. It must be an absolute path or a
@@ -79,7 +80,7 @@ The typical location of the **conan.conf** file is the directory ``~/.conan/``:
     # You can skip the proxy for the matching (fnmatch) urls (comma-separated)
     # no_proxy_match = *bintray.com*, https://myserver.*
 
-    [hooks]  # environment CONAN_HOOKS
+    [hooks]    # environment CONAN_HOOKS
     attribute_checker
 
     # Default settings now declared in the default profile
@@ -191,6 +192,10 @@ in the conan code base, allowing to debug the detected error.
 The ``cacert_path`` variable lets the user specify a custom path to the *cacert.pem* file to use
 in requests. You can also adjust this value using the environment variable ``CONAN_CACERT_PATH``.
 
+The ``scm_to_conandata`` variable tells Conan to store the resolved information of the :ref:`SCM feature<scm_feature>` in the
+:ref:`conandata.yml<conandata_yml>` file instead of modifying the recipe file itself. You can also adjust
+this value using the environment variable ``CONAN_SCM_TO_CONANDATA``.
+
 The ``skip_broken_symlinks_check`` variable (defaulted to ``False``) allows the existence broken symlinks while creating a package.
 
 Storage

reference/config_files/conandata.yml.rst

@@ -3,7 +3,7 @@
 conandata.yml
 =============
 
-This YAML file can be used to in the recipe to declare specific information to be used inside the recipe. This file is specific to each
+This YAML file can be used to declare specific information to be used inside the recipe. This file is specific to each
 recipe *conanfile.py* and it should be placed next to it. The file is automatically exported with the recipe (no need to add it to
 :ref:`exports_attribute` attribute) and its content is loaded into the :ref:`conandata_attribute` attribute of the recipe.
 
@@ -24,3 +24,8 @@ For example:
         patches: "0001-beast-fix-moved-from-executor.patch,bcp_namespace_issues.patch"
       1.71.0:
         patches: "bcp_namespace_issues.patch,boost_build_qcc_fix_debug_build_parameter.patch"
+
+
+.. note::
+
+    The first level entry key ``.conan`` is reserved for Conan usage.