Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: try to clarify some confusion with run_exports. #914

Merged
merged 2 commits into from
Oct 4, 2023
Merged

docs: try to clarify some confusion with run_exports. #914

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
93e2ab6
Update check_build_help.py
johanneskoester Aug 25, 2023
55bcd6c
Update check_build_help.py
johanneskoester Aug 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 17 additions & 6 deletions bioconda_utils/lint/check_build_help.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,9 @@ class missing_run_exports(LintCheck):
libraries) but also for e.g. Python packages, as those might also
introduce breaking changes in their APIs or command line interfaces.

We distinguish between three cases. If the software follows semantic versioning (or it has at least a normal version string (like 1.2.3) and the actual strategy of the devs is unknown), add run_exports to the recipe like this::
We distinguish between four cases.

**Case 1:** If the software follows semantic versioning (or it has at least a normal version string (like 1.2.3) and the actual strategy of the devs is unknown), add run_exports to the recipe like this::

build:
run_exports:
Expand All @@ -160,16 +162,20 @@ class missing_run_exports(LintCheck):
This will by default pin the package to ``>=1.2.0,<2.0.0`` where ``1.2.0`` is the
version of the package at build time of the one depending on it and ``<2.0.0`` constrains
it to be less than the next major (i.e. potentially not backward compatible) version.

**Case 2:** If the software version starts with a 0 (e.g. ``0.3.2``) semantic versioning allows breaking changes in minor releases. Hence, you should use::

build:
run_exports:
- {{ pin_subpackage('myrecipe', max_pin="x.x") }}

If the software has a normal versioning (like 1.2.3) but does reportedly not follow semantic versioning, please choose the ``max_pin`` argument such that it captures the potential next version that will introduce a breaking change. E.g. if you expect breaking changes to occur with the next minor release, choose ``max_pin="x.x"``, if they even can occur with the next patch release, choose ``max_pin="x.x.x"``.
**Case 3:** If the software has a normal versioning (like 1.2.3) but does reportedly not follow semantic versioning, please choose the ``max_pin`` argument such that it captures the potential next version that will introduce a breaking change.
E.g. if you expect breaking changes to occur with the next minor release, choose ``max_pin="x.x"``, if they even can occur with the next patch release, choose ``max_pin="x.x.x"``.

If the software does have a non-standard versioning (e.g. calendar versioning like 20220602), we cannot really protect well against breakages. However, we can at least pin to the current version as a minimum and skip the max_pin constraint. This works by setting ``max_pin=None``.
**Case 4:** If the software does have a non-standard versioning (e.g. calendar versioning like 20220602), we cannot really protect well against breakages. However, we can at least pin to the current version as a minimum and skip the max_pin constraint. This works by setting ``max_pin=None``.

In the recipe depending on this one, one just needs to specify the package name
and no version at all.
If you need a different pinning strategy for this particular recipe (e.g. because it does
not follow semantic versioning), you can e.g. use ``max_pin="x.x"`` to pin to the minor
version (i.e. translating to ``>=1.2.0,<1.3.0`` ).

Also check out the possible arguments of `pin_subpackage` here:
https://docs.conda.io/projects/conda-build/en/stable/resources/define-metadata.html#export-runtime-requirements
Expand All @@ -183,6 +189,11 @@ class missing_run_exports(LintCheck):
Finally, note that conda is unable to conduct such pinnings in case the dependency and the depending recipe
are updated within the same pull request. Hence, the pull request adding the run_export statement
has to be merged before the one updating or creating the depending recipe is created.

**Importantly** note that this shall not be used to pin compatible versions of other recipes in the current recipe.
Rather, those other recipes have to get their own run_exports sections.
Usually, there is no need to use ``pin_compatible``, just use ``pin_subpackage`` as shown above, and fix
run_exports in upstream packages as well if needed.
"""
def check_recipe(self, recipe):
build = recipe.meta.get("build", dict())
Expand Down