Guidance for building POMs

When building the POM for a plugin there are multiple goals.

1. We want the POM to represent a consistent state of an IdP (this would usually be the minimum IdP Version the plugin supports).
2. We want to avoid any dependency leakage from the IdP into the plugin (and any projects deriving from the IdP).
3. We want to avoid the project or plugin developer from accidentally shipping jars in the plugin which are subject to restrictive licenses that do not allow us to ship them. Such Jars need to be downloaded by the deployer and there is an infrastructure that deploys this.

We, therefore, have come up with the following guidance

• The plugin pom SHOULD have the idp-parent project as its parent (or an ancestor).
  • This saves a great deal of boilerplate and removes from the plugin author the need to keep on top of any dependencies which come via the IdP.  So for example, if a security alert causes an IdP dependency to be revised this happens for free for the plugin.  Equally compiler versions and other "best IdP development practices" are inherited at no cost.
    • This also includes, amongst others, the IdP license. This should be overridden if required.
• Each release version of the plugin SHOULD be built from a release version of the idp-parent pom. This version would usually be the lowest version that the plugin supports.
• It is recommended that a CI build is set up using the current SNAPSHOT idp-parent pom as an ancestor. This will allow the developer to determine if parent pom changes are getting in the way of the plugins interoperability and therefore allow it to tailor its compatibility story.
  • Remember compatibility is not built-in when the plugin ships, but is dynamically established from a known HTTP endpoint; A CI build makes it automatic the testing of a plugin against the next major IdP version as soon as development starts.
• All dependencies of the plugin MUST be explicitly mentioned in the plugin project’s pom (this is just hygiene)
  • All IdP supplied dependencies MUST have scope ‘provided’ (or 'test').  This avoids jar pollution downstream from the plugin (or technically from where they are 'provided'). Note that ‘provided’ implies ‘test’ so plugins can be tested outside an IdP and the dependencies will turn up.
  • All dependencies which cannot be shipped (e.g. due to restrictive licensing as mentioned) MUST have scope ‘provided’; this avoids accidental shipping is the maven dependency plugin used to build the distributable.
  • Depending on the kitting mechanism used, required and shippable dependencies MAY have scope ‘compile’.
• IdP dependencies SHOULD be limited to ‘api’. This allows a wide range of IdP versions to be supported (usually, but not always up to but not including the next major version) . ‘impl’ dependencies by their nature imply that exactly one version of the IdP is supported.
  • That said, test dependencies of 'impl' plugin modules MAY depend on IdP 'impl' dependencies to facilitate unit or integration tests.
    • It is unlikely that 'api' plugin modules will require IdP 'impl' test dependencies. If they do, either the IdP 'impl' dependency needs to be exposed as part of the API, or the plugin's API needs refactoring.
• Consider adding shadowing to any assemble stages

It is worth noting that the idp-parent project is less than perfect as a parent project since declares several dubious dependencies which should be managed and mentioned expliclty.  See  IDP-1620 - Getting issue details... STATUS

Naming

Just sketching out and recording some plausible naming conventions.

The example is one I'm working on for TOTP login flow support. In my example, the only "varying" portion seems to be the "totp" fragment and the rest might be standardized...

Git Repo: java-idp-plugin-totp

Parent POM coordinates:

    <name>Shibboleth IdP :: Plugins :: TOTP Login Flow</name>
    <groupId>net.shibboleth.idp.plugin</groupId>
    <artifactId>idp-plugin-totp</artifactId>

Typical submodules:

    <modules>
        <module>totp-impl</module>
        <module>totp-dist</module>
    </modules>

Implementation POM:

    <name>Shibboleth IdP :: Plugins :: TOTP Login Flow Impl</name>
    <artifactId>idp-plugin-totp-impl</artifactId>

    <properties>
        <automatic.module.name>net.shibboleth.idp.plugin.totp.impl</automatic.module.name>
    </properties>

Distribution POM:

    <name>Shibboleth IdP :: Plugins :: TOTP Login Flow Distribution</name>
    <artifactId>idp-plugin-totp-dist</artifactId>
    <packaging>pom</packaging>

    <properties>
        <dist.finalName>shibboleth-idp-plugin-totp-${project.version}</dist.finalName>
    </properties>