Skip to main content
Jump to: navigation, search

LocationTech/The Nexus

< LocationTech
Revision as of 17:31, 9 January 2019 by Wayne.beaton.eclipse-foundation.org (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Tips and tricks (not yet a user's guide) to using the LocationTech Nexus Maven Repository.

For more information:

Nexus

The LocationTech Nexus is used to host a number of maven repositories, playing a role similar to Orbit for OSGi projects.

The main user interface is available here:

The initial user interface search field is restricted due to security permissions, click on the Repositories link to browse contents manually.

LocationTechNexus.png

Published Repositories

All repositories mentioned here are considered published and are available for access to external parties.

The moment you deploy an artefact please consider it "gone" and replicated out to all users of your library. If you must delete something please do so in close collaboration with your development list as you will need to ask each developer to delete files from ~/.m2/repository/org/locationtech

LocationTech maven repository URLs can be accessed using either "group" or the recommended "repositories". We have used "repositories" in all the following examples.

Releases Repository

The releases repository is limited to artifacts that have been through the CQ process (and thus reviewed by the IP team).

There are three categories of artifacts that may be published here:

  • Artifacts produced by the Eclipse Foundation (including LocationTech). These artifacts undergo a release review with the IP Team.
  • Artifacts that have been approved "as written" by the IP Team. These artifacts are published using the exact same pom.xml as maven central.
  • Artifacts that have a subset approved by the IP Team. These artifacts are published using a maven classifier to avoid confusion and conflict with artifacts provided by maven central

To use this repository in your project:

 <repositories>
   <repository>
     <releases>
       <enabled>true</enabled>
       <updatePolicy>never</updatePolicy>
       <checksumPolicy>fail</checksumPolicy>
     </releases>
     <snapshots>
       <enabled>false</enabled>
       <updatePolicy>never</updatePolicy>
       <checksumPolicy>fail</checksumPolicy>
     </snapshots>
   </repository>
     <id>LocationTechReleases</id>
     <name>LocationTech Releases</name>
     <url>https://repo.locationtech.org/content/repositories/releases/</url>
     <layout>default</layout>
   </repository>
 </repositories>

For more information on using repositories please see Introduction to Repositories.

Snapshots Repository

Used to host artefacts produced by nightly builds. Due to their transitory nature these artifacts have not been reviewed by the IP team and are in no way considered official.

This repository is intended for:

  • SNAPSHOT artifacts produced by a nightly build (or deployed manually by a member of the development team)

To use this repository in your project:

 <repositories>
   <repository>
     <releases>
       <enabled>false</enabled>
       <updatePolicy>never</updatePolicy>
       <checksumPolicy>fail</checksumPolicy>
     </releases>
     <snapshots>
       <enabled>true</enabled>
       <updatePolicy>daily</updatePolicy>
       <checksumPolicy>warn</checksumPolicy>
     </snapshots>
   </repository>
     <id>LocationTechSnapshots</id>
     <name>LocationTech Snapshots</name>
     <url>https://repo.locationtech.org/content/repositories/snapshots/</url>
     <layout>default</layout>
   </repository>
 </repositories>

Project Specific Releases and Snapshots Repositories

Project specific repositories are available on request, perhaps used for informal collaboration between projects around beta releases, or to catch surprise transitive dependencies being added during a nightly build.

Examples:

Third-party Repository

The LocationTech Nexus server hosts artifacts which have been approved by the Eclipse IP/legal team. The repo is here: https://repo.locationtech.org/content/repositories/thirdparty/

Publishing ip-approved (and potentially subsetted) artifacts to the server is a multi-step process.

  1. One will need to have write access to the /shared directory which is attached to the LocationTech Hudson servers as well as other build servers. This will require 'shell access'; you can request this access from http://portal.eclipse.org/
  2. Once you have shell access, you can scp the jars to a path under /shared/.
  3. From there, follow the directions here: https://wiki.eclipse.org/Services/Nexus#Deploying_artifacts_to_repo.eclipse.org in order to create a Hudson job which will deploy artifacts to the Nexus server.

Build Considerations

CQ Management and Use of Release Profile

The publishing of artifacts (jars, source and javadocs) requires careful consideration for others. For developers integrating our content we have to very carefully avoid conflict with other development teams and follow the guidelines used for publishing artifacts to maven central.

Each artifacts has three terms deterring its coordinates:

  • groupId: identify your project uniquely across all projects
  • artifactId: is the name of the jar without version
  • version: recommend version with numbers and dots (1.0, 1.1, 1.0.1, ...)

With each artefact being made available via:

  • classifier: jar, source, javadoc etc...

In addition to the standard classifiers mentioned above, teams have used classifiers to publish debug or aop builds if a jar. We will use this same facility to publish CQ subsets below.

Publishing Unmodified

When publishing our own work (or publishing work approved "as written" by the CQ process) this is straight forward as outlined here:

Please be advised that this approach only works for *unmodified* artifacts as the maven repository system is willing to cache the first copy of the jar obtained (for example from maven central, your national mirror, or team repository).

Formally Publishing a Subset

When publishing a work that has only been approved in part buy the CQ process (described as a "subset" in Orbit) we are left with a conflict. Technically this work is a fork, with the following advice from Choosing your Coordinates:

However if the project does maintain a presence on Central, then if there's a fork you have two choices:

  • B1) get the original project to upload the artifacts in their own groupId (unlikely since there's a reason it was a fork)
  • B2) upload them under your the forked project groupId (presumably one you own and appropriate for the fork)

It is of course preferable to ask authors to fix any IP issues encountered and avoid the need for subsets.

Using this advice you may publish a "subset" using your own project co-ordinates:

 <dependency>
   < !-- uDig project has jcommon 1.0.16 subset approved for distribution as CQ7581 -->
   <groupId>org.locationtech.udig.jfree</groupId>
   <artifactId>jcommon</artifactId>
   <version>1.0.16-CQ7581</version>
 </dependency>

Do not be surprised if your subset ends up being re-published by other repositories. This is by design, and why you have provided a unique coordinate for your fork.

Using a subset for release

One way to protect consumers of your library from managing the complexity of a formal subset it to switch between:

  • Deploy artifacts using unmodified dependencies: This prevents the proliferation of forks ... users of your library will fulfil these transitive dependencies from maven central rather than the LocationTech repository
  • Assemble releases using subset dependencies: The jars assembled for distribution are limited to those approved by the CQ process

For this approach each subset is published using the CQ number as the classifier. This allows different teams to work with alternative subsets of the same dependency.

   <profile>
       <id>locationtech.publish-false</id>
       <activation>
          <property>
             <name>!publish</name>
          </property>           
       </activation>
       <dependencies>
         <dependency>
           <groupId>jfree</groupId>
           <artifactId>jcommon</artifactId>
           <version>1.0.16</version>
           <classifier>CQ7581</classifier>
         </dependency>
       </dependencies>          
   </profile>    
   <profile>
       <id>locationtech.publish-true</id>
       <activation>
          <property>
             <name>publish</name>
          </property>           
       </activation>
       <dependencies>
         <dependency>
           <groupId>jfree</groupId>
           <artifactId>jcommon</artifactId>
           <version>1.0.16</version>
         </dependency>
       </dependencies>          
   </profile>

The above example alternates between two dependencies based on the use of the "publish" system property.

When deploying your project (to maven for others to depend on) use the publish system property:

     mvn deploy:deploy -Dpublish
  

When assembling the final artifacts (into an zip or installer for users to download) use maven like normal:

     mvn assemble

For more information please see https://bugs.eclipse.org/bugs/show_bug.cgi?id=528560

Deployment of non Java Artifacts

The maven build repository system has been adopted by many build environments including Ant (XML), Gradle (Groovy) and sbt (Scala).

When deploying artifacts written in other languages it is best to respect community conventions.

Scala

The scala docs provide the following naming conventions for packages:

Scala packages should follow the Java package naming conventions:

// wrong!
package coolness
// right!
package com.novell.coolness
// right, for package object com.novell.coolness
package com.novell
/**
  * Provides classes related to coolness
  */
package object coolness {
}

The community has ignored this convention and instead settled on very short package names: play, spray, akka, dispatch, scalar, spire, shapeless, argonaut, monocle, slick

For more information please see https://bugs.eclipse.org/bugs/show_bug.cgi?id=528563

Back to the top