mod_compat_roles: New module providing compat shim for trunk's new role API The new role API is translated to is_admin() calls on older versions. On newer versions (which have the role API) this module does nothing. It allows modules to drop their use of is_admin() (which is not available in trunk) and switch to the new role API, while remaining compatible with previous Prosody versions.

author: Matthew Wild <mwild1@gmail.com>
date: Thu, 11 Aug 2022 17:49:33 +0100
child: 4984:fc6a618bfe4e
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_compat_roles/README.markdown	Thu Aug 11 17:49:33 2022 +0100
@@ -0,0 +1,49 @@
+---
+labels:
+- Stage-Alpha
+summary: 'Compatibility layer for Prosody's future roles API'
+...
+
+Introduction
+============
+
+This module provides compatibility with Prosody's new role and permissions
+system. It aims to run on Prosody 0.11 and 0.12, providing a limited version
+of the new API backed by is_admin() (which is not going to be present in trunk
+and future Prosody versions).
+
+It is designed for use by modules which want to be compatible with Prosody
+versions with and without the new permissions API.
+
+Configuration
+=============
+
+There is no configuration.
+
+Usage (for developers)
+======================
+
+If you are a module developer, and want your module to work with Prosody trunk
+and future releases, you should avoid the `usermanager.is_admin()` function.
+
+Instead, depend on this module:
+
+```
+module:depends("compat_roles")
+```
+
+Then use `module:may()` instead:
+
+```
+if module:may(":do-something") then
+  -- Blah
+end
+```
+
+For more information on the new role/permissions API, check Prosody's
+developer documentation at https://prosody.im/doc/developers/permissions
+
+Compatibility
+=============
+
+Requires Prosody 0.11 or 0.12.