From 3338bb98e615ec79147f7aa5f0ca88d4ba468101 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johannes=20K=C3=B6ster?= <johannes.koester@uni-due.de>
Date: Thu, 17 Aug 2023 17:04:07 +0200
Subject: [PATCH] lint description

---
 bioconda_utils/cli.py                   |  5 ++++-
 bioconda_utils/lint/__init__.py         |  2 +-
 bioconda_utils/lint/check_build_help.py | 22 +++++++++++++---------
 test/lint_cases.yaml                    |  1 +
 4 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/bioconda_utils/cli.py b/bioconda_utils/cli.py
index 917d463fc9..b572df25ba 100644
--- a/bioconda_utils/cli.py
+++ b/bioconda_utils/cli.py
@@ -353,7 +353,10 @@ def do_lint(recipe_folder, config, packages="*", cache=None, list_checks=False,
     messages = linter.get_messages()
 
     if messages:
-        print("The following problems have been found:\n")
+        print(
+            "The following problems have been found (visit https://bioconda.github.io/contributor/linting.html "
+            "for details on the particular lints you get below.):\n"
+        )
         print(linter.get_report())
 
     if not result:
diff --git a/bioconda_utils/lint/__init__.py b/bioconda_utils/lint/__init__.py
index c16b755575..82be133ea3 100644
--- a/bioconda_utils/lint/__init__.py
+++ b/bioconda_utils/lint/__init__.py
@@ -487,7 +487,7 @@ def __init__(self, config: Dict, recipe_folder: str,
         try:
             self.checks_ordered = reversed(list(nx.topological_sort(dag)))
         except nx.NetworkXUnfeasible:
-            raise RunTimeError("Cycle in LintCheck requirements!")
+            raise RuntimeError("Cycle in LintCheck requirements!")
         self.reload_checks()
 
     def reload_checks(self):
diff --git a/bioconda_utils/lint/check_build_help.py b/bioconda_utils/lint/check_build_help.py
index f6407ffd8b..1ac51929ff 100644
--- a/bioconda_utils/lint/check_build_help.py
+++ b/bioconda_utils/lint/check_build_help.py
@@ -139,8 +139,9 @@ def check_deps(self, deps):
 
 
 class missing_run_exports(LintCheck):
-    """Every recipe should have a run_export statement that ensures
-    that the package is automatically pinned to a compatible version if
+    """Recipe should have a run_export statement that ensures correct pinning in downstream packages
+
+    This ensures that the package is automatically pinned to a compatible version if
     it is used as a dependency in another recipe.
     This is a conservative strategy to avoid breakaged. We came to the 
     conclusion that it is better to require this little overhead instead
@@ -149,21 +150,24 @@ 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.
 
-
     Add run_exports to the recipe like this::
 
       build:
         run_exports:
-          - {{ pin_subpackage('myrecipe') }}
+          - {{ pin_subpackage('myrecipe', max_pin="x") }}
+
+    with ``myrecipe`` being the name of the recipe (you can also use the name variable).
+    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.
 
-    with ``myrecipe`` being the name of the recipe. This will by default pin the
-    package to ``>=x.x.x,<y.0.0`` where ``x.x.x`` is the version of the package at
-    build time of the one depending on it, and ``y = x + 1`` is the next major 
-    (i.e. potentially not backward compatible) version.
     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), check out the possible arguments of `pin_subpackage` here:
+    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
 
     Since this strategy can lead to potentially more conflicts in dependency pinnings between tools,
diff --git a/test/lint_cases.yaml b/test/lint_cases.yaml
index 52c307bde4..a9d882a509 100644
--- a/test/lint_cases.yaml
+++ b/test/lint_cases.yaml
@@ -102,6 +102,7 @@ tests:
           - missing_license
           - missing_build_number
           - missing_summary
+          - missing_run_exports
           - missing_tests
           - no_tests
           - gpl_requires_license_distributed