[develop2] versioning (#2920)

* [develop2] versioning * Update tutorial/versioning.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * Update tutorial/versioning.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * Update tutorial/versioning/version_ranges.rst Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> * Update tutorial/versioning/version_ranges.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update tutorial/versioning/version_ranges.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update tutorial/versioning/versions.rst Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> * Update reference/conanfile/attributes.rst Co-authored-by: SSE4 <tomskside@gmail.com> * Update tutorial/versioning/version_ranges.rst Co-authored-by: SSE4 <tomskside@gmail.com> * wip * review * wip * wip * wip * wip * wip * done! * Update tutorial/versioning/conflicts.rst Co-authored-by: SSE4 <tomskside@gmail.com> * wip * new graphviz diagrams --------- Co-authored-by: Carlos Zoido <mrgalleta@gmail.com> Co-authored-by: Rubén Rincón Blanco <git@rinconblanco.es> Co-authored-by: SSE4 <tomskside@gmail.com>
conan-io · Feb 10, 2023 · 65acd2d · 65acd2d
1 parent b2c08c8
commit 65acd2d
Show file tree

Hide file tree

Showing 16 changed files with 1,362 additions and 120 deletions.
diff --git a/conf.py b/conf.py
@@ -104,7 +104,7 @@
 
 # General information about the project.
 project = u'conan'
-copyright = u'2016-2022, JFrog'
+copyright = u'2016-2023, JFrog'
 author = u'The Conan team'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -423,49 +423,7 @@
 # copy legacy redirects
 def copy_legacy_redirects(app, docname): # Sphinx expects two arguments
     # FILL in this dicts the necessary redirects
-    redirect_files = {
-        "creating_packages/package_dev_flow.html": "../developing_packages/package_dev_flow.html",
-        "conan1.0.html": "faq/conan1.0.html",
-        "mastering/python_requires.html": "../extending/python_requires.html",
-        "mastering/version_ranges.html": "../versioning/version_ranges.html",
-        "mastering/revisions.html": "../versioning/revisions.html",
-
-        "integrations/cmake.html": "build_system/cmake.html",
-        "integrations/makefile.html": "build_system/makefile.html",
-        "integrations/ninja.html": "build_system/ninja.html",
-        "integrations/pkg_config_pc_files.html": "build_system/pkg_config_pc_files.html",
-        "integrations/boost_build.html": "build_system/boost_build.html",
-        "integrations/b2.html": "build_system/b2.html",
-        "integrations/qmake.html": "build_system/qmake.html",
-        "integrations/premake.html": "build_system/premake.html",
-        "integrations/make.html": "build_system/make.html",
-        "integrations/qbs.html": "build_system/qbs.html",
-        "integrations/meson.html": "build_system/meson.html",
-        "integrations/scons.html": "build_system/scons.html",
-        "integrations/gcc.html": "build_system/gcc.html",
-
-        "integrations/docker.html": "cross_platform/docker.html",
-        "integrations/qnx_neutrino.html": "cross_platform/qnx_neutrino.html",
-        "integrations/emscripten.html": "cross_platform/emscripten.html",
-
-        "integrations/visual_studio.html": "ide/visual_studio.html",
-        "integrations/xcode.html": "ide/xcode.html",
-        "integrations/android_studio.html": "ide/android_studio.html",
-        "integrations/clion.html": "ide/clion.html",
-        "integrations/youcompleteme.html": "ide/youcompleteme.html",
-
-        "integrations/git.html": "vcs/git.html",
-
-        "integrations/jenkins.html": "ci/jenkins.html",
-        "integrations/travisci.html": "ci/travisci.html",
-        "integrations/appveyor.html": "ci/appveyor.html",
-        "integrations/gitlab.html": "ci/gitlab.html",
-        "integrations/circleci.html": "ci/circleci.html",
-        "integrations/azure_devops.html": "ci/azure_devops.html",
-
-        "integrations/other.html": "custom.html",
-        "integrations/pylint.html": "linting.html",
-
+    redirect_files = {    
     }
 
     redirect_template = """<!DOCTYPE html>

diff --git a/reference/conanfile/attributes.rst b/reference/conanfile/attributes.rst
@@ -394,12 +394,22 @@ requires
 
   Accepted expressions would be:
 
-    ..  code-block:: python
-
-          >1.1 <2.1    # In such range
-          2.8          # equivalent to =2.8
-          ~=3.0        # compatible, according to semver
-          >1.1 || 0.8  # conditions can be OR'ed
+    .. list-table::
+        :widths: 25 25 50
+        :header-rows: 1
+
+        * - Expression
+          - Versions in range
+          - Versions outside of range
+        * - [>=1.0 <2]
+          - 1.0.0, 1.0.1, 1.1, 1.2.3
+          - 0.2, 2.0, 2.1, 3.0
+        * - [<3.2.1]
+          - 0.1, 1.2, 2.4, 3.1.1
+          - 3.2.2
+        * - [>2.0]
+          - 2.1, 2.2, 3.1, 14.2
+          - 1.1, 1.2, 2.0
 
 
   .. seealso::

diff --git a/tutorial.rst b/tutorial.rst
@@ -22,6 +22,5 @@ libraries and store them in a remote server alongside all the precompiled binari
    tutorial/consuming_packages
    tutorial/creating_packages
    tutorial/conan_repositories
-   tutorial/versioning_ci
+   tutorial/versioning
    tutorial/other_features
-
diff --git a/tutorial/consuming_packages/intro_to_versioning.rst b/tutorial/consuming_packages/intro_to_versioning.rst
@@ -213,5 +213,5 @@ allowed range ``zlib/[~1.2]``, because the ``conan.lock`` lockfile is forcing it
 Read more
 ---------
 
-- :ref:`Introduction to Versioning and Continuous Integration <tutorial_versioning_ci>`
+- :ref:`Introduction to Versioning<tutorial_versioning>`
 
diff --git a/tutorial/versioning.rst b/tutorial/versioning.rst
@@ -0,0 +1,35 @@
+.. _tutorial_versioning:
+
+
+Versioning
+==========
+
+This section of the tutorial introduces several concepts about versioning of packages.
+
+First, explicit version updates and how to define versions of packages is explained.
+
+Then, it will be introduced how ``requires`` with version ranges can 
+help to automate updating to the latest versions.
+
+There are some situations when recipes or source code are changed, but the version of the
+package is not increased. For those situations, Conan uses automatic ``revisions`` to 
+be able to provide traceability and reproducibility of those changes.
+
+Lockfiles are a common mechanism in package managers to be able to reproduce the same
+dependency graph later in time, even when new versions or revisions of dependencies are uploaded.
+Conan also provides lockfiles to be able to guarantee this reproducibility.
+
+Finally, when different branches of a dependency graph ``requires`` different versions of the
+same package, that is called a "version conflict". The tutorial will also introduce these
+errors and how to address them.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Table of contents
+
+   versioning/versions
+   versioning/version_ranges
+   versioning/revisions
+   versioning/lockfiles
+   versioning/conflicts