Updating documentation to describe ~= package specification

docs/source/resources/package-spec.rst

@@ -62,7 +62,7 @@ conda package is composed of the first 3 values, as in:
 ``<name>-<version>-<build>.tar.bz2`` or ``<name>-<version>-<build>.conda``.
 
 .. list-table::
-   :widths: 15 15 70
+   :widths: 15 15 45
 
    * - **Key**
      - **Type**
@@ -76,8 +76,7 @@ conda package is composed of the first 3 values, as in:
    * - version
      - string
      - The package version. May not contain "-". Conda
-       acknowledges `PEP 440
-       <https://www.python.org/dev/peps/pep-0440/>`_.
+       acknowledges `PEP 440 <https://www.python.org/dev/peps/pep-0440/>`_.
 
    * - build
      - string
@@ -100,9 +99,9 @@ conda package is composed of the first 3 values, as in:
        the package.
 
        Unlike the build string, the ``build_number`` is inspected by
-       conda. Conda uses it to sort packages that have otherwise
-       identical names and versions to determine the latest one.
-       This is important because new builds that contain bug
+       conda. Conda uses |br| it to sort packages that have otherwise
+       identical names and versions |br| to determine the latest one.
+       This is important because new builds that |br| contain bug
        fixes for the way a package is built may be added to a
        repository.
 
@@ -126,7 +125,7 @@ conda package is composed of the first 3 values, as in:
        EXAMPLE: ``osx``
 
        Conda currently does not use this key. Packages for a
-       specific architecture and platform are usually
+       specific architecture and platform are |br| usually
        distinguished by the repository subdirectory that contains
        them---see :ref:`repo-si`.
 
@@ -284,86 +283,98 @@ parts:
 * The first part is always the exact name of the package.
 
 * The second part refers to the version and may contain special
-  characters:
+  characters.  See table below.
 
-  * \| means OR.
+* The third part is always the exact build string. When there are
+  3 parts, the second part must be the exact version.
 
-    EXAMPLE: ``1.0|1.2`` matches version 1.0 or 1.2.
+.. list-table:: Version Special Characters
+   :widths: 10, 40, 40
+   :header-rows: 1
 
-  * \* matches 0 or more characters in the version string. In
-    terms of regular expressions, it is the same as ``r'.*'``.
+   * - Symbol
+     - Meaning
+     - Example
 
-    EXAMPLE: 1.0|1.4* matches 1.0, 1.4 and 1.4.1b2, but not 1.2.
+   * - <, >, <=, >=
+     - Relational operators on versions, |br| which are compared using `PEP-440 <https://www.python.org/dev/peps/pep-0440/>`_.
+     - ``<=1.0`` matches 0.9, 0.9.1, and 1.0, but not 1.0.1.
 
-  * <, >, <=, >=, ==, and != are relational operators on versions,
-    which are compared using
-    `PEP-440 <https://www.python.org/dev/peps/pep-0440/>`_. For example,
-    ``<=1.0`` matches ``0.9``, ``0.9.1``, and ``1.0``, but not ``1.0.1``.
-    ``==`` and ``!=`` are exact equality.
+   * - ==, and !=
+     - Exact equality and not equalities.
+     - ``==0.5.1`` matches 0.5.1 and not anything else while ``!=0.5.1`` matches everything but.
 
-    Pre-release versioning is also supported such that ``>1.0b4`` will match
-    ``1.0b5`` and ``1.0rc1`` but not ``1.0b4`` or ``1.0a5``.
+   * - ~=
+     - Compatibility Release
+     - ``~=0.5.3`` equivalent to say ``>=0.5.3, <0.6.0a``
 
-    EXAMPLE: <=1.0 matches 0.9, 0.9.1, and 1.0, but not 1.0.1.
+   * - \|
+     - OR
+     - ``1.0|1.2`` matches version 1.0 or 1.2.
 
-  * , means AND.
+   * - \*
+     - Matches 0 or more characters in the version string. |br| In terms of regular expressions, it is the same as ``r'.*'``.
+     - ``1.0|1.4*`` matches 1.0, 1.4 and 1.4.1b2, but not 1.2.
 
-    EXAMPLE: >=2,<3 matches all packages in the 2 series. 2.0,
-    2.1, and 2.9 all match, but 3.0 and 1.0 do not.
+   * - ,
+     - AND
+     - ``>=2,<3`` matches all packages in the 2 series. |br| 2.0, 2.1, and 2.9 all match, but 3.0 and 1.0 do not.
 
-  * , has higher precedence than \|, so >=1,<2|>3 means greater
-    than or equal to 1 AND less than 2 or greater than 3, which
-    matches 1, 1.3 and 3.0, but not 2.2.
+.. hint::
+   ``,`` has higher precedence than \|, so >=1,<2|>3 means greater than or equal to 1 AND less than 2 or greater than 3, which matches 1, 1.3 and 3.0, but not 2.2.
 
-  Conda parses the version by splitting it into parts separated
-  by \|. If the part begins with <, >, =, or !, it is parsed as a
-  relational operator. Otherwise, it is parsed as a version,
-  possibly containing the "*" operator.
+.. note::
+   For package match specifications, pre-release versioning is also supported such that ``>1.0b4`` will match ``1.0b5`` and ``1.0rc1`` but not ``1.0b4`` or ``1.0a5``.
 
-* The third part is always the exact build string. When there are
-  3 parts, the second part must be the exact version.
+Conda parses the version by splitting it into parts separated
+by \|. If the part begins with <, >, =, or !, it is parsed as a
+relational operator. Otherwise, it is parsed as a version,
+possibly containing the "*" operator.
 
 Remember that the version specification cannot contain spaces,
 as spaces are used to delimit the package, version, and build
 string in the whole match specification. ``python >= 2.7`` is an
 invalid match specification. However, ``"python >= 2.7"`` (with double or single quotes) is
 matched as any version of a package named ``python>=2.7``.
 
-When using the command line, put double or single quotes around any package
-version specification that contains the space character or any of
-the following characters: <, >, \*, or \|.
+Examples of Package Specs
+-------------------------
 
-EXAMPLE::
+The build string constraint "numpy=1.11.2=*nomkl*" matches the NumPy 1.11.2 packages without MKL but not the normal MKL NumPy
+1.11.2 packages.
 
-  conda install numpy=1.11
-  conda install numpy==1.11
-  conda install "numpy>1.11"
-  conda install "numpy=1.11.1|1.11.3"
-  conda install "numpy>=1.8,<2"
+The build string constraint "numpy=1.11.1|1.11.3=py36_0" matches NumPy 1.11.1 or 1.11.3 built for Python 3.6 but not any versions
+of NumPy built for Python 3.5 or Python 2.7.
 
 
-Examples
---------
+Command Line Match Spec Examples
+--------------------------------
 
-The OR constraint "numpy=1.11.1|1.11.3" matches with 1.11.1 or
-1.11.3.
+When using the command line, put double or single quotes around any package
+version specification that contains the space character or any of
+the following characters: <, >, \*, or \|.
 
-The AND constraint "numpy>=1.8,<2" matches with 1.8 and 1.9 but
-not 2.0.
+.. list-table:: Examples
+   :widths: 30 60
+   :header-rows: 1
 
-The fuzzy constraint numpy=1.11 matches 1.11, 1.11.0, 1.11.1,
-1.11.2, 1.11.18, and so on.
+   * - Example
+     - Meaning
 
-The exact constraint numpy==1.11 matches 1.11, 1.11.0, 1.11.0.0,
-and so on.
+   * - conda install numpy=1.11
+     - The fuzzy constraint numpy=1.11 matches 1.11, 1.11.0, 1.11.1, 1.11.2, 1.11.18, and so on.
 
-The build string constraint "numpy=1.11.2=*nomkl*" matches the
-NumPy 1.11.2 packages without MKL but not the normal MKL NumPy
-1.11.2 packages.
+   * - conda install numpy==1.11
+     - The exact constraint numpy==1.11 matches 1.11, 1.11.0, 1.11.0.0, and so on.
 
-The build string constraint "numpy=1.11.1|1.11.3=py36_0" matches
-NumPy 1.11.1 or 1.11.3 built for Python 3.6 but not any versions
-of NumPy built for Python 3.5 or Python 2.7.
+   * - conda install "numpy=1.11.1|1.11.3"
+     - The OR constraint "numpy=1.11.1|1.11.3" matches with 1.11.1 or 1.11.3.
+
+   * - conda install "numpy>1.11"
+     - Any numpy version 1.12.0a or greater.
+
+   * - conda install "numpy>=1.8,<2"
+     - The AND constraint "numpy>=1.8,<2" matches with 1.8 and 1.9 but not 2.0.
 
 The following are all valid match specifications for
 numpy-1.8.1-py27_0:
@@ -378,3 +389,7 @@ numpy-1.8.1-py27_0:
 * numpy >=1.8,<2|1.9
 * numpy 1.8.1 py27_0
 * numpy=1.8.1=py27_0
+
+.. |br| raw:: html
+
+      <br>

news/4553-document-compatibility-release-operator

@@ -0,0 +1,3 @@
+### Docs
+
+* Document `~=` (compatibility release) match spec. (#4553)