Permalink
Browse files

Merge pull request #7 from mads379/patch-1

Forked @janm399's repo to make this pull request as he was having problems with the pull requests.
  • Loading branch information...
mads-hartmann committed Feb 2, 2012
2 parents c7bd941 + 5fff0f4 commit 1d77c2f1516028a8d44dc1126d1979eff9aad126
Showing with 92 additions and 21 deletions.
  1. +92 −21 src/jekyll/using_sonatype.md
@@ -16,48 +16,48 @@ You'll need to PGP sign your artifacts for the Sonatype repository. Don't worry
To publish to a maven repository, you'll need to configure a few settings so that the correct metadata is generated.
-{% highlight scala %}
+```scala
publishMavenStyle := true
-{% endhighlight %}
+```
is used to ensure POMs are generated and pushed. Next, you have to set up the repositories you wish to push too. Luckily, Sonatype's OSSRH uses the same URLs for everyone:
-{% highlight scala %}
+```scala
publishTo <<= version { (v: String) =>
val nexus = "https://oss.sonatype.org/"
if (v.trim.endsWith("SNAPSHOT")) Some("snapshots" at nexus + "content/repositories/snapshots")
else Some("releases" at nexus + "service/local/staging/deploy/maven2")
}
-{% endhighlight %}
+```
Another good idea is to not publish your test artifacts:
-{% highlight scala %}
+```scala
publishArtifact in Test := false
-{% endhighlight %}
+```
## Third - POM Metadata ##
Now, we want to control what's available in the `pom.xml` file. This file describes our project in the maven repository and is used by indexing services for search and discover. This means it's important that `pom.xml` should have all information we wish to advertise as well as required info!
First, let's make sure no repositories show up in the POM file. To publish on maven-central, all *required* artifacts must also be hosted on maven central. However, sometimes we have optional dependencies for special features. If that's the case, let's remove the repositories for optional dependencies in our artifact:
-{% highlight scala %}
-pomIncludeRepository := { x => false },
-{% endhighlight %}
+```scala
+pomIncludeRepository := { x => false }
+```
Next, the POM metadata that isn't generated by SBT must be added. This is done through the `pomExtra` configuration option:
-{% highlight xml %}
+```scala
pomExtra := (
<url>http://jsuereth.com/scala-arm</url>
- <licenses>
- <license>
- <name>BSD-style</name>
- <url>http://www.opensource.org/licenses/bsd-license.php</url>
- <distribution>repo</distribution>
- </license>
- </licenses>
+ <licenses>
+ <license>
+ <name>BSD-style</name>
+ <url>http://www.opensource.org/licenses/bsd-license.php</url>
+ <distribution>repo</distribution>
+ </license>
+ </licenses>
<scm>
<url>git@github.com:jsuereth/scala-arm.git</url>
<connection>scm:git:git@github.com:jsuereth/scala-arm.git</connection>
@@ -69,7 +69,7 @@ pomExtra := (
<url>http://jsuereth.com</url>
</developer>
</developers>)
-{% endhighlight %}
+```
Specifically, the `url`, `license`, `scm.url`, `scm.connection` and `developer` sections are required. The above is an example from the [scala-arm](http://jsuereth.com/scala-arm) project.
@@ -79,9 +79,10 @@ Specifically, the `url`, `license`, `scm.url`, `scm.connection` and `developer`
The credentails for your Sonatype OSSRH account need to be added somewhere. Common convention is a `~/.sbt/sonatype.sbt` file with the following:
-{% highlight scala %}
-credentials += Credentials("Sonatype Nexus Repository Manager", "oss.sonatype.org", "<your username>", "<your password>")
-{% endhighlight %}
+```scala

This comment has been minimized.

Show comment Hide comment
@jsuereth

jsuereth Feb 2, 2012

Member

Does this syntax work with command-line jekyll?

@jsuereth

jsuereth Feb 2, 2012

Member

Does this syntax work with command-line jekyll?

This comment has been minimized.

Show comment Hide comment
@mads-hartmann

mads-hartmann Feb 2, 2012

Member
@mads-hartmann

mads-hartmann via email Feb 2, 2012

Member

This comment has been minimized.

Show comment Hide comment
@jsuereth

jsuereth Feb 2, 2012

Member

Already done!

Note: The website should show it's final form on http://scala-sbt.org/using_sonatype.html.

Those {% highlight scala %} are jekyll notations to do pygment highlighting. I turned it off because it was really ugly in the resulting page anyway.

@jsuereth

jsuereth Feb 2, 2012

Member

Already done!

Note: The website should show it's final form on http://scala-sbt.org/using_sonatype.html.

Those {% highlight scala %} are jekyll notations to do pygment highlighting. I turned it off because it was really ugly in the resulting page anyway.

This comment has been minimized.

Show comment Hide comment
@mads-hartmann

mads-hartmann Feb 2, 2012

Member

Great, thanks :)

@mads-hartmann

mads-hartmann Feb 2, 2012

Member

Great, thanks :)

+credentials += Credentials("Sonatype Nexus Repository Manager", "oss.sonatype.org",
+ "<your username>", "<your password>")
+```
*Note: The first two strings **must** be `"Sonatype Nexus Repository Manager"` and `"oss.sonatype.org"` for Ivy to use the credentials.*
@@ -116,5 +117,75 @@ After publishing you have to follow the [Release workflow of nexus](https://docs
*Note: Staged releases allow testing across large projects of independent releases before pushing the full project.*
+## Summary ##
+To get your project hosted on Sonatype (and Maven Central), you will need to:
+* Have GPG key pair, with published public key,
+* A SBT file with your Sonatype credentials *that is not pushed to the VCS*,
+* Modify `project/plugins.sbt` to include the `xsbt-gpg-plugin` to sign the artefacts,
+* Modify `build.sbt` with the required elements in the generated POM.
+
+Starting with a project that is not being published, you'll need to install GPG, generate and publish your key. Swtiching to SBT,
+you'll then need to:
+
+#### ~/.sbt/sonatype.sbt
+
+This file (kept *outside the VCS*) contains the Sonatype credentials settings:
+
+```scala
+credentials += Credentials("Sonatype Nexus Repository Manager",
+ "oss.sonatype.org",
+ "your-sonatype-username",
+ "your-sonatype-password")
+```
+
+#### project/plugins.sbt
+
+This file specifies the plugins for your project. If you intend to sign the artefacts, you'll need to include @jsuereth's `xsbt-gpg-plugin`:
+
+```scala
+resolvers += "sbt-plugin-releases" at "http://scalasbt.artifactoryonline.com/scalasbt/sbt-plugin-releases/"
+
+addSbtPlugin("com.jsuereth" % "xsbt-gpg-plugin" % "0.5")
+```
+
+#### build.sbt
+
+Finally, you'll need to tweak the generated POM in your `build.sbt`. The tweaks include specifying the project's authors, URL, SCM and many others:
+
+```scala
+publishTo <<= version { v: String =>
+ val nexus = "https://oss.sonatype.org/"
+ if (v.trim.endsWith("SNAPSHOT")) Some("snapshots" at nexus + "content/repositories/snapshots")
+ else Some("releases" at nexus + "service/local/staging/deploy/maven2")
+}
+
+publishMavenStyle := true
+
+publishArtifact in Test := false
+
+pomIncludeRepository := { x => false }
+
+pomExtra := (
+ <url>http://your.project.url</url>
+ <licenses>
+ <license>
+ <name>BSD-style</name>
+ <url>http://www.opensource.org/licenses/bsd-license.php</url>
+ <distribution>repo</distribution>
+ </license>
+ </licenses>
+ <scm>
+ <url>git@github.com:your-account/your-project.git</url>
+ <connection>scm:git:git@github.com:your-account/your-project.git</connection>
+ </scm>
+ <developers>
+ <developer>
+ <id>you</id>
+ <name>Your Name</name>
+ <url>http://your.url</url>
+ </developer>
+ </developers>
+)
+```

2 comments on commit 1d77c2f

@janm399

This comment has been minimized.

Show comment Hide comment
@janm399

janm399 Feb 2, 2012

Sorry I wasn't in touch--there's one more day of meetings ahead of me. I'll be much more sociable on Friday.

Sorry I wasn't in touch--there's one more day of meetings ahead of me. I'll be much more sociable on Friday.

@mads-hartmann

This comment has been minimized.

Show comment Hide comment
@mads-hartmann

mads-hartmann Feb 2, 2012

Member

No problem - Had some spare time this morning and thought I might as well get your changes in :)

Member

mads-hartmann replied Feb 2, 2012

No problem - Had some spare time this morning and thought I might as well get your changes in :)

Please sign in to comment.