Publishing Artifacts

This page will explain the system for publishing artifacts to BinTray, as used by some NetLogo branches and repositories.

BinTray

BinTray is a place to which artifacts are uploaded. If you want to publish artifacts for the NetLogo organization on BinTray, you should create an account on BinTray and let Jason know what your username is, so he can add you. (You'll get an invitation by email, which you'll need to accept.) You shouldn't have to touch BinTray much at all after that.

You might notice that all of the existing projects that publish to BinTray or depend on artifacts from BinTray use the SBT BinTray plugin. You shouldn't have to deal with this too much, either, as it operates mostly behind-the-scenes. When you go to publish for the first time (or if you run bintray::changeCredentials in SBT before first attempting to publish), you will be asked to enter your BinTray credentials. Enter your username and the API key that you get from https://bintray.com/profile/edit (in the "API Key" section). After that one time of entering your credentials, its use should be largely transparent to you.

That's all that setting yourself up for using BinTray really entails.

publish-versioned

In order to do the actual publishing, you should use the publish-versioned task, which comes from the publish-versioned SBT plugin. There's lots of pressure from certain sources on the team for us to be publishing well-versioned artifacts in order to facilitate having reproducible builds, and leveraging SBT to give us such a versioning scheme seems like the logical way to go about this. The plugin enforces the following versioning scheme for us:

If isSnapshot is false in the project's build, your artifacts will be published using the build's original value for the version setting. Otherwise, the plugin will call out to Git to determine the SHA of the current commit and append that to the version number, and will also append "-dirty" to the version number if the Git repo has uncommitted changes.

Consequently, you should almost never publish dirty builds, and you should absolutely never make commits that rely upon "dirty" dependencies. If an artifact is dirty, it's not well-versioned, so using it runs the risk of breaking our whole "reproducible builds" thing. It's trivial to make a proper commit out of your changes; just do that.

Regarding isSnapshot, virtually the only time you want that to be false is if you're making an official release.

Since the publish-versioned plugin has a dynamic way of determining the version of the artifact, it becomes largely impractical to publish with SBT's standard publish command, since that relies upon version by default, and version essentially cannot be seamlessly changed while SBT is running. As a result, do not publish artifacts by using publish. Instead, use the publish-versioned task that is provided by the plugin. This task does what we actually want by performing publish with our dynamically-determined version value. It is also discouraged to use package (which should no longer have much use, anyway), and you are urged to, in its place, use the package-versioned task provided by the publish-versioned plugin. If you're into publish-local, there's also a publish-local-versioned task that can be used.

Workflow

Pushing out new artifacts is super simple!

Let's assume you have Repo A and Repo B, where Repo B depends on an artifact from Repo A. From SBT in Repo A, run publish-versioned. Then, in Repo B's dependency configuration, update the version number for Repo A's artifact(s) (the version number can be seen printed out numerous times in the output of the publish-versioned task). That's it!

Depending Anew

If Repo B isn't already configured to pull down the dependency from Repo A, first make sure that Repo B uses the BinTray plugin. If not, add this to project/plugins.sbt for Repo B:

resolvers += Resolver.url(
  "bintray-sbt-plugin-releases",
    url("http://dl.bintray.com/content/sbt/sbt-plugin-releases"))(
        Resolver.ivyStylePatterns)

addSbtPlugin("me.lessis" % "bintray-sbt" % "0.1.2")

Then, add your dependency line in Repo B like you usually would (e.g. "org.nlogo" % "netlogoheadless" % "5.2.0-abcdef1") and add the BinTray settings to the build through either

bintrayResolverSettings

or, if you plan to both depend and publish,

bintraySettings

That should be all.

(On certain occasions, you may need to add a resolver line like resolvers += bintray.Opts.resolver.repo("netlogo", "NetLogoHeadless") in order to depend upon an artifact, but for the 'headless' branch and the Tortoise repo, the artifacts are mirrored to BinTray's JCenter, so you don't have to worry about adding an extra resolver for them.)

Publishing Anew

First, make sure that your project uses the BinTray SBT plugin. If not, add this to your project/plugins.sbt:

resolvers += Resolver.url(
  "bintray-sbt-plugin-releases",
    url("http://dl.bintray.com/content/sbt/sbt-plugin-releases"))(
        Resolver.ivyStylePatterns)

addSbtPlugin("me.lessis" % "bintray-sbt" % "0.1.2")

I also recommend using the publish-versioned plugin, which you can add with

resolvers += Resolver.url(
  "publish-versioned-plugin-releases",
    url("http://dl.bintray.com/content/netlogo/publish-versioned"))(
        Resolver.ivyStylePatterns)

addSbtPlugin("org.nlogo" % "publish-versioned-plugin" % "2.0")

Then, ensure that the following settings are in your SBT build:

• name := [the name of your project]
• organization := [probably '"org.nlogo"']
• licenses += ([license name], [URL])
• isSnapshot := [probably 'true']
• version := [your project's version number]
• bintrayPublishSettings (or bintraySettings, if you'll also be depending on projects from BinTray)
• PublishVersioned.settings
• bintray.Keys.repository in bintray.Keys.bintray := [the name of your repo on BinTray]
• bintray.Keys.bintrayOrganization in bintray.Keys.bintray := Some([your username or organization name on BinTray])

WARNING: Also, setting artifactName in your build is generally a bad idea, as I have seen it direly break at least one BinTray repository, causing a mysterious "content is not allowed in prolog" message when depending on the artifacts uploaded with artifactName altered. (The immediate cause of the error being that, for whatever reason, SBT pulls down the documentation .jar and tries to treat it as an ivy.xml file.)

Assuming you have properly created your repository on BinTray, publish-versioned should then work seamless for you.