Merge branch 'main' into main

.github/dependabot.yml

@@ -0,0 +1,15 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/docs/"
+    schedule:
+      interval: "weekly"
+    allow:
+      # Allow only production updates for Sphinx
+      - dependency-name: "sphinx"
+        dependency-type: "production"

.github/workflows/labels.yml

@@ -20,7 +20,7 @@ jobs:
       GLOBAL: https://raw.githubusercontent.com/conda/infra/main/.github/global.yml
       LOCAL: .github/labels.yml
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - id: has_local
         uses: andstor/[email protected]
         with:

.pre-commit-config.yaml

@@ -58,7 +58,7 @@ repos:
       # auto sort Python imports
       - id: isort
   - repo: https://github.com/psf/black
-    rev: 23.7.0
+    rev: 23.9.1
     hooks:
       # auto format Python codes
       - id: black

.readthedocs.yml

@@ -1,7 +1,11 @@
 version: 2
 
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+
 python:
-  version: "3"
   install:
   - requirements: docs/requirements.txt
 

docs/requirements.txt

@@ -1,7 +1,7 @@
 linkify-it-py==1.0.1
 myst-parser==0.15.2
 Pillow==9.3.0
-PyYAML==5.4.1
+PyYAML==6.0.1
 requests==2.31.0
 ruamel.yaml==0.17.16
 Sphinx==4.2.0

docs/source/install-conda-build.rst

@@ -9,6 +9,42 @@ To enable building conda packages:
 * update conda and conda-build
 
 
+.. _-conda-build-wow:
+
+Way of working
+==============
+
+For proper functioning, it is strongly recommended to install conda-build in
+the conda ``base`` environment. Not doing so may lead to problems.
+
+Explanation
+-----------
+
+With earlier conda / conda-build versions, it was possible to build packages in
+your own defined environment, e.g. ``my_build_env``. This was partly driven by
+the general conda recommendation not to use the ``base`` env for normal work;
+see `Conda Managing Environments`_ for instance. However, conda-build is better
+viewed as part of the conda infrastructure, and not as a normal package. Hence,
+installing it in the ``base`` env makes more sense. More information:
+`Must conda-build be installed in the base envt?`_
+
+Other considerations
+--------------------
+
+* An installation or update of conda-build (in fact, of any package) in the ``base``
+  environment needs to be run from an account with the proper permissions
+  (i.e., the same permissions as were used to install conda and the base env in
+  the first place via the Miniconda or Anaconda installers). For example, on
+  Windows that might mean an account with administrator privileges.
+
+* `conda-verfiy`_ is a useful package that can also be added to the base
+  environment in order to remove some warnings generated when conda-build runs.
+
+* For critical CI/CD projects, you might want to pin to an explicit (but recent)
+  version of conda-build, i.e. only update to a newer version of conda-build
+  and conda once they have been first verified "offline".
+
+
 .. _install-conda-build:
 
 Installing conda-build
@@ -18,6 +54,7 @@ To install conda-build, in your terminal window or an Anaconda Prompt, run:
 
 .. code-block:: bash
 
+   conda activate base
    conda install conda-build
 
 
@@ -31,8 +68,14 @@ To update conda and conda-build, in your terminal window or an Anaconda Prompt,
 
 .. code-block:: bash
 
+  conda activate base
   conda update conda
   conda update conda-build
 
 For release notes, see the `conda-build GitHub
 page <https://github.com/conda/conda-build/releases>`_.
+
+
+.. _`Conda Managing Environments`:                      https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-environments
+.. _`conda-verfiy`:                                     https://github.com/conda/conda-verify
+.. _`Must conda-build be installed in the base envt?`:  https://github.com/conda/conda-build/issues/4995

docs/source/resources/define-metadata.rst

@@ -992,9 +992,10 @@ words, a Python package would list ``python`` here and an R package would list
 
 The PREFIX environment variable points to the host prefix. With respect to
 activation during builds, both the host and build environments are activated.
-The build prefix is activated before the host prefix so that the host prefix
-has priority over the build prefix. Executables that don't exist in the host
-prefix should be found in the build prefix.
+The build prefix is activated *after* the host prefix so that the build prefix,
+which always contains native executables for the running platform, has priority
+over the host prefix, which is not guaranteed to provide native executables (e.g.
+when cross-compiling).
 
 As of conda-build 3.1.4, the build and host prefixes are always separate when
 both are defined, or when ``{{ compiler() }}`` Jinja2 functions are used. The

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
@@ -96,15 +95,13 @@ conda package is composed of the first 3 values, as in:
 
    * - build_number
      - integer
-     - A non-negative integer representing the build number of
-       the package.
+     - A non-negative integer representing the build number of 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
-       fixes for the way a package is built may be added to a
-       repository.
+       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 fixes for the way a package is built may be added to a repository.
 
    * - depends
      - list of strings
@@ -125,10 +122,12 @@ 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
-       distinguished by the repository subdirectory that contains
-       them---see :ref:`repo-si`.
+       Conda currently does not use this key.
+
+       Packages for a specific architecture and platform are usually distinguished by the repository subdirectory that contains
+       them.
+
+       See :ref:`repo-si`.
 
 info/files
 ----------
@@ -284,85 +283,73 @@ 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
+  three 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,
 
-  * <, >, <=, >=, ==, 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.
+       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.
 
-    Pre-release versioning is also supported such that ``>1.0b4`` will match
-    ``1.0b5`` and ``1.0rc1`` but not ``1.0b4`` or ``1.0a5``.
+   * - ==, and !=
+     - Exact equality and not equalities.
+     - ``==0.5.1`` matches 0.5.1 and not anything else while ``!=0.5.1`` matches everything but.
 
-    EXAMPLE: <=1.0 matches 0.9, 0.9.1, and 1.0, but not 1.0.1.
+   * - ~=
+     - Compatibility Release
+     - ``~=0.5.3`` is equivalent to ``>=0.5.3, <0.6.0a``
 
-  * , means AND.
+   * - \|
+     - OR
+     - ``1.0|1.2`` matches version 1.0 or 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.
+   * - \*
+     - Matches 0 or more characters in the version string.
 
-  * , 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.
+       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.
 
-  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.
+   * - ,
+     - AND
+     - ``>=2,<3`` matches all packages in the 2 series.
 
-* The third part is always the exact build string. When there are
-  3 parts, the second part must be the exact version.
+       2.0, 2.1, and 2.9 all match, but 3.0 and 1.0 do not.
+
+.. 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.
+
+.. 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``.
+
+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 \|.
-
-EXAMPLE::
-
-  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"
-
+Examples of Package Specs
+-------------------------
 
-Examples
---------
-
-The OR constraint "numpy=1.11.1|1.11.3" matches with 1.11.1 or
-1.11.3.
-
-The AND constraint "numpy>=1.8,<2" matches with 1.8 and 1.9 but
-not 2.0.
-
-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 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.2=*nomkl*" matches the
-NumPy 1.11.2 packages without MKL but not the normal MKL NumPy
+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.
 
-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
+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.
 
 The following are all valid match specifications for
@@ -378,3 +365,32 @@ numpy-1.8.1-py27_0:
 * numpy >=1.8,<2|1.9
 * numpy 1.8.1 py27_0
 * numpy=1.8.1=py27_0
+
+Command Line Match Spec Examples
+--------------------------------
+
+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 \|.
+
+.. list-table:: Examples
+   :widths: 30 60
+   :header-rows: 1
+
+   * - Example
+     - Meaning
+
+   * - 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.
+
+   * - conda install numpy==1.11
+     - The exact constraint numpy==1.11 matches 1.11, 1.11.0, 1.11.0.0, and so on.
+
+   * - 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.

news/4553-document-compatibility-release-operator

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

news/4942-docs-prefix-activation

@@ -0,0 +1,19 @@
+### Enhancements
+
+* <news item>
+
+### Bug fixes
+
+* <news item>
+
+### Deprecations
+
+* <news item>
+
+### Docs
+
+* Clarify that the `build` prefix is activated _after_ the `host` prefix. (#4942)
+
+### Other
+
+* <news item>