Page Comparison

...

1. We want the POM to represent dependency on a consistent state of an IdP (this would usually be the minimum IdP Version 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 NOT 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 startsIt MAY, if produced by the Shibboleth Project, use the java-parent-project POM as its parent, generally the version corresponding to the minimum IdP version supported.
  • While this leads to some duplication, relying on idp-parent directly causes dependency contamination and causes unrelated settings connected to site generation to leak into plugins.
• 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 accidentally shipping is the maven dependency plugin used to build the distributablein the final package.
  • Depending on the kitting mechanism used, newly required and shippable dependencies MAY have scope ‘compile’. But note that we do not have the capability of preventing plugin dependencies from conflicting. If this is a concern, shadowing is the only real answer (see below).
• IdP and OpenSAML 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’ Non-API dependencies by their nature imply that exactly one version of the IdP is supported without explicit testing.
  
  • 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 

• Plugins MAY consider using shadowing during assembly to embed specific dependency versions, though the IdP itself will (almost certainly) never do so.

Project Naming

Just sketching out and recording some plausible naming conventions for the project's own plugins...

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...examples are based on a plugin providing a "feature".

Git Repo: java-idp-plugin-totpfeature

Parent POM coordinates:

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

Typical submodules:

    <modules>
        <module>feature-api</module> <!-- perhaps, many plugins won't have an API -->
    <module>totp    <module>feature-impl</module>
        <module>totp<module>feature-dist</module>
    </modules>

...

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

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

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <executions>
                    <execution>
                        <id>copy-dependencies</id>
                        <phase>package</phase>
                        <goals>
                            <goal>copy-dependencies</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>${project.target.directory}</outputDirectory>
                            <includeScope>runtime</includeScope>
                            <excludeTransitive>true</excludeTransitive>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId> 
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <configuration>
                    <archive>
                        <manifestEntries>
                            <Automatic-Module-Name>${automatic.module.name}</Automatic-Module-Name>
                        </manifestEntries>
                    </archive>
                </configuration>
            </plugin>
        </plugins>
    </build>

Distribution POM:

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

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