Policies: Add docs on how to specify version support post-36; fix ruc…

…io#404

docs/operator/policy_packages.md

@@ -33,43 +33,67 @@ is suffixed with the VO name (for example, `package-vo1` or
 The structure of a policy package is very simple. It can contain the
 following:
 
-- A `permission.py` module implementing permission
-  customisations (optional).
-- A `schema.py` module implementing schema customisations (optional).
 - An `__init__.py` file that:
   - indicates the supported Rucio version via the `SUPPORTED_VERSION` field;
   - indicates the algorithms provided by the package (optional)
+- A `permission.py` module implementing permission
+  customisations (optional).
+- A `schema.py` module implementing schema customisations (optional).
 
-The `permission.py` and `schema.py` modules are optional; an experiment
-that does not need to customise these modules can omit one or both of
-them from the policy package and the Rucio generic versions will be
-used instead. If these modules are required, the easiest way to create
-them is to modify the generic versions from the Rucio codebase. These
-can be found in `lib/rucio/core/permission/generic.py` and
-`lib/rucio/common/schema/generic.py` respectively.
+### `__init__.py`
 
-The `has_permission` function in the permission module may return `None`
-if your experiment does not implement a custom permission check for a
-particular action. In this case, the generic permission module will be
-called for this action instead.
+#### `SUPPORTED_VERSION`
 
-The schema module of a policy package does not need to define all of
-the schema values. Any missing ones will automatically be loaded from
-the generic schema module instead.
+`__init__.py` should define a `str | list[str]` called `SUPPORTED_VERSION`,
+indicating the version(s) of Rucio that your package supports. 
 
-`__init__.py` should include a
-`SUPPORTED_VERSION` field indicating the major version(s) of Rucio
-that your package supports. This is checked against the Rucio server
-version to ensure compatibility when loading the policy package. This
-field can be a string if the policy package only supports a single
-Rucio version, or a list of strings if it supports multiple versions.
-Example:
+This is checked against the Rucio server
+version to ensure compatibility when loading the policy package. 
+
+##### From Rucio 36
+From Rucio 36, version checking was modified 
+to use [PEP-compliant version specifiers](https://peps.python.org/pep-0440/#version-specifiers).
+
+For example, to specify support for the entire Rucio 36 release line (so 36.1.0, 36.2.0...) 
+without yet supporting Rucio 37, 
+the [**compatible release** operator](https://peps.python.org/pep-0440/#compatible-release) `~=`
+can be used, as seen below.
+
+```python
+SUPPORTED_VERSION = '~=36.0'
+```
+
+Multiple constraints can be specified, either as a string:
+
+```python
+SUPPORTED_VERSION = '~=36.0,!=36.4.0'
+```
+
+Or as a list:
+
+```python
+SUPPORTED_VERSION = ['~=36.0','!=36.4.0']
+```
+
+##### Before Rucio 36
+
+On Rucio versions older than 36, only major versions can be specified.
+This can be done as either a string:
+
+```python
+SUPPORTED_VERSION = '35'
+```
+
+Or as a list, to indicate support for multiple major versions:
 
 ```python
-SUPPORTED_VERSION = [ "1.30", "1.31", "32" ]
+SUPPORTED_VERSION = ['34', '35']
 ```
 
-It can also contain an optional function called `get_algorithms` that
+#### `get_algorithms`
+
+The `__init__.py` file can also contain 
+an optional function called `get_algorithms` that
 returns a dictionary of custom algorithms implemented within the package.
 In fact, this structure should be a "dictionary of dictionaries" where
 the outer dictionary contains algorithm types, and each inner
@@ -109,32 +133,28 @@ In all cases the names used to register the functions (e.g. `voname_extract_scop
 with the name of the virtual organisation that owns the policy package,
 to avoid naming conflicts on multi-VO Rucio installations.
 
-### lfn2pfn vs. non_deterministic_pfn algorithms
+### Permission and schema modules
 
-`lfn2pfn` algorithms and `non_deterministic_pfn` algorithms are
-conceptually similar, but there are important differences between
-them. Both produce a physical filename for use on an RSE, however
-`lfn2pfn` algorithms can only be used on deterministic RSEs - for
-example, disk systems where the appropriate physical filename can be
-derived from the file's scope and name alone (as well as
-protocol-specific information for the RSE in question).
-`non_deterministic_pfn` algorithms are used on non-deterministic
-RSEs (most often tape systems), and may use additional information
-about the file (such as its metadata, any datasets that it is a part
-of, etc.) to construct the physical filename. Because files cannot
-be uploaded directly to non-deterministic storage,
-`non_deterministic_pfn` algorithms are only ever called for
-replications, but `lfn2pfn` algorithms can also be called for
-initial uploads.
+The `permission.py` and `schema.py` modules are optional; an experiment
+that does not need to customise these modules can omit one or both of
+them from the policy package and the Rucio generic versions will be
+used instead. If these modules are required, the easiest way to create
+them is to modify the generic versions from the Rucio codebase. These
+can be found in `lib/rucio/core/permission/generic.py` and
+`lib/rucio/common/schema/generic.py` respectively.
 
-The `lfn2pfn` algorithm to be used is determined by the
-`lfn2pfn_algorithm` attribute of the relevant RSE. If this is not set,
-the `lfn2pfn_algorithm_default` value from the `[policy]` section of
-the config file is used instead. The `non_deterministic_pfn` algorithm
-to be used is determined by the `naming_convention` attribute of the
-relevant RSE.
+The `has_permission` function in the permission module may return `None`
+if your experiment does not implement a custom permission check for a
+particular action. In this case, the generic permission module will be
+called for this action instead.
+
+The schema module of a policy package does not need to define all of
+the schema values. Any missing ones will automatically be loaded from
+the generic schema module instead.
 
-## Adding a new algorithm class
+## Policy algorithms
+
+### Adding a new algorithm class
 
 The system for registering algorithms within policy packages is
 intended to be extensible so that new algorithm classes can be added
@@ -157,6 +177,31 @@ relatively easily. The basic workflow is as follows:
   importing the package if necessary, and dealing with multiple
   packages in multi-VO Rucio installations.
 
+### lfn2pfn vs. non_deterministic_pfn algorithms
+
+`lfn2pfn` algorithms and `non_deterministic_pfn` algorithms are
+conceptually similar, but there are important differences between
+them. Both produce a physical filename for use on an RSE, however
+`lfn2pfn` algorithms can only be used on deterministic RSEs - for
+example, disk systems where the appropriate physical filename can be
+derived from the file's scope and name alone (as well as
+protocol-specific information for the RSE in question).
+`non_deterministic_pfn` algorithms are used on non-deterministic
+RSEs (most often tape systems), and may use additional information
+about the file (such as its metadata, any datasets that it is a part
+of, etc.) to construct the physical filename. Because files cannot
+be uploaded directly to non-deterministic storage,
+`non_deterministic_pfn` algorithms are only ever called for
+replications, but `lfn2pfn` algorithms can also be called for
+initial uploads.
+
+The `lfn2pfn` algorithm to be used is determined by the
+`lfn2pfn_algorithm` attribute of the relevant RSE. If this is not set,
+the `lfn2pfn_algorithm_default` value from the `[policy]` section of
+the config file is used instead. The `non_deterministic_pfn` algorithm
+to be used is determined by the `naming_convention` attribute of the
+relevant RSE.
+
 ## Deploying Policy Packages in containers
 
 It is now common to deploy Rucio using containers managed by software