pypa#1599 - add unit test for combined pinned and latest version filt…

…ering as well as clarifying comments in documentation

docs/filtering_configuration.md

@@ -13,6 +13,10 @@ converted.
 E.g. to Blocklist [discord.py](https://pypi.org/project/discord.py/) the string 'discord-py'
 is correct, but 'discord.PY' will also work.
 
+Plugins for release version filtering usually act in a way, that releases are only downloaded if all filter plugin rules are satisfied.
+An exception to this rule is the `project_requirements_pinned` filter: if there is a version number/range specified no other filter are applied.
+This allows smaller mirrors with newest versions and specifically needed ones.
+
 ## Plugins Enabling
 
 The plugins setting is a list of plugins to enable.

src/bandersnatch/tests/plugins/test_allowlist_name.py

@@ -406,6 +406,43 @@ def test__filter__matches__release(self) -> None:
 
         self.assertEqual({"1.2.0": {}}, pkg.releases)
 
+    def test__filter__matches__release_latest(self) -> None:
+        with open(Path(self.tempdir.name) / "requirements.txt", "w") as fh:
+            fh.write("""\
+#    This is needed for workshop 1
+#
+foo==1.2.0             # via -r requirements.in
+""")
+
+        mock_config(f"""\
+[mirror]
+storage-backend = filesystem
+workers = 2
+
+[plugins]
+enabled =
+    project_requirements
+    project_requirements_pinned
+    latest_release
+[latest_release]
+keep = 2
+[allowlist]
+requirements_path = {self.tempdir.name}
+requirements =
+    requirements.txt
+""")
+
+        mirror = BandersnatchMirror(Path("."), Master(url="https://foo.bar.com"))
+        pkg = Package("foo", 1)
+        pkg._metadata = {
+            "info": {"name": "foo"},
+            "releases": {"1.2.0": {}, "1.2.1": {}, "1.2.2": {}},
+        }
+
+        pkg.filter_all_releases(mirror.filters.filter_release_plugins())
+
+        self.assertEqual({"1.2.0": {}}, pkg.releases)
+
     def test__filter__find_files(self) -> None:
         absolute_file_path = Path(self.tempdir.name) / "requirements.txt"
         with open(absolute_file_path, "w") as fh: