Adding new permission to control panel configlet in Plone

I'm adding a new permission to an add-on to allow a user with Site Manager role to be able to access its control panel configlet.

I followed Plone's documentation on creating custom permissions, but I don't understand the need for the rolemap.xml file, as my permission is up and running without it:

<configure xmlns="http://namespaces.zope.org/zope"
    xmlns:browser="http://namespaces.zope.org/browser">

  ...

  <permission
      id="collective.upload.Setup"
      title="collective.upload: Setup">
    <role name="Manager"/>
    <role name="Site Administrator"/>
  </permission>

  <browser:page
      name="upload-settings"
      for="Products.CMFPlone.interfaces.IPloneSiteRoot"
      class="collective.upload.controlpanel.UploadSettingsControlPanel"
      permission="collective.upload.Setup"
      />

</configure>

Do I need to use a rolemap.xml here or not?

For creating a new permission you don't need any rolemap.xml: the permission will be created with default settings you can see in the root of your Zope application, but there you have few roles visible.

rolemap.xml is used to assign permissions to roles in the context of the Plone site where the add-on is installed.

I fear that with the configuration you did you have a side effects:

• you assigned the permission to the "Site Administrator" role in the ZMI root (where the role is not defined)
• you will simply see the "acquire" check selected for the permission in you Plone site root "security" tab

Things still works here but you don't have any explicit view from ZMI of how/where Site Administrator get this permissions.

I find the usage of rolemap.xml a cleaner solution (commonly I also set to False the "acquire permission settings").