Get rid of example-permissions.yml, it's been a long-standing source of confusion

docs/permissions-reference.md

@@ -1,6 +1,6 @@
 # PyLink Permissions Reference
 
-Below is a list of all the permissions defined by PyLink and its official plugins. For instructions on how to fine-tune permissions, see [example-permissions.yml](../example-permissions.yml).
+Below is a list of all the permissions defined by PyLink and its official plugins.
 
 ## PyLink Core
 - `core.clearqueue` - Grants access to the `clearqueue` command.

example-conf.yml

@@ -104,14 +104,29 @@ login:
             #hosts: ["*!*@localhost", "*!*@trusted.isp"]
 
 permissions:
-    # Permissions are described in more detail in example-permissions.yml, if you want to
+    # Permissions blocks in PyLink are define as a mapping of PyLink targets (i.e. hostmasks or
-    # customize permissions further.
+    # exttargets) to lists of permission nodes. You can find a list of permissions that PyLink and
+    # its plugins define in docs/permissions-reference.md.
+
+    # Permissions blocks look something like this:
+    #"*!user@host":
+    #    - "permission.node.1"
+    #    - "permission.node.2"
+    #    - "someplugin.*"  # Wildcards are also supported in names
 
     # Replace ABC123 with your PyLink account name (configured above)
     # in order to give yourself admin access.
     "ABC123":
         - "*"
 
+# This option determines whether plugin-determined default permissions should be enabled.
+# You should generally only disable this if you need to configure permissions in a specific way,
+# because it WILL break features people expect to work (e.g. access to Relay commands) unless you
+# configure that in.
+# See docs/permissions-reference.md for a list of permissions defined by PyLink's stock plugins.
+# This defaults to true if not set.
+#permissions_merge_defaults: true
+
 servers:
     # Please note: these are only EXAMPLE link blocks. You should edit them and
     # remove ones that you don't need in your config.

example-permissions.yml

@@ -1,51 +0,0 @@
-# This file is an example of the permissions system in PyLink. To fine-tune permissions, you should
-# merge the "permissions:" block in this file with the one in your PyLink configuration, creating it
-# if it doesn't already exist. Simply renaming this file to permissions.yml DOES NOT work!
-
-# Permissions work by mapping hostmasks, accounts, and exttargets to lists of permissions, allowing
-# you to fine tune which users have access to which commands.
-
-# If you do not specify any permissions block in your configuration, PyLink will default to a
-# permission set defined by plugins, which usually correspond to the list below, but can be
-# changed on every release.
-
-# This determines whether we should merge plugins' built-in default permissions with the ones specified
-# in the following permissions: block. Disabling this allows you greater control over the permissions
-# PyLink gives, but you should check this file on every major update to see if any new permissions
-# were added for commands. Otherwise, commands that were available before may cease to function!
-permissions_merge_defaults: true
-
-permissions:
-    # Note: It is a good idea to quote any exttargets or hostmasks so the configuration parser knows
-    # they are raw strings.
-
-    "$ircop":
-        # The default set of Automode permissions allow you to manage any channels you own in Relay.
-        # If Relay is not loaded, this check will fail. This has the ability of allowing local opers
-        # to manage their channels, but not abusing Automode to hack modes in other networks' relay
-        # channels.
-        - automode.manage.relay_owned
-        - automode.sync.relay_owned
-        - automode.list
-
-        # These allow opers to manage Relay links on their network.
-        - relay.create
-        - relay.destroy
-        - relay.claim
-        - relay.link
-        - relay.delink
-        - relay.linkacl.view
-        - relay.linkacl
-
-    "*!*@*":
-        # The following permissions are given to all users by default.
-        - relay.linked
-        - commands.status
-        - commands.showuser
-        - commands.showchan
-
-    # Replace ABC123 with your PyLink account name (configured above)
-    # in order to give yourself admin access.
-    "$pylinkacc:ABC123":
-        - "*"
-

setup.py

@@ -93,7 +93,7 @@ setup(
 
     # Data files
     package_data={
-        '': ['example-conf.yml', 'example-permissions.yml', 'VERSION', 'README.md'],
+        '': ['example-conf.yml', 'VERSION', 'README.md'],
     },
 
     package_dir = {'pylinkirc': '.'},