I Failed the Turing Test

你需要：

1. 一個使用 Maven 管理的 Java project（廢話）
2. 一個 GPG key（deploy 的時候會用來 sign 要提交的 .jar）
3. 一個 Sonatype JIRA 的帳號
4. 開一張 JIRA 的 ticket 告訴 Sonatype 的人你要發佈 library，告知他們你的 groupId
5. 按照 Requirements 的指示完善你的 pom.xml
6. deploy 到 snapshot repository
7. deploy 到 staging repository
8. 在 OSSRH 的 Staging Repositories 把你剛剛 deploy 的 library 給 close 掉，這樣才算是 release
9. 回到那張 ticket，通知 Sonatype 讓他們把你的 library 同步到 Maven Central Repositir

最後一個步驟只有第一次 release 的時候才需要
之後 release 就會自動同步了

Requirements

http://maven.apache.org/guides/mini/guide-central-repository-upload.html
http://central.sonatype.org/pages/requirements.html
http://central.sonatype.org/pages/ossrh-guide.html
http://central.sonatype.org/pages/apache-maven.html
http://central.sonatype.org/pages/releasing-the-deployment.html

參考 Pangu.java 的 pom.xml
https://github.com/vinta/pangu.java/blob/master/pom.xml

Deployment

You need following plugins:

• maven-source-plugin
• maven-javadoc-plugin
• maven-gpg-plugin
• nexus-staging-maven-plugin
• maven-release-plugin

deploy 之前
必須確定你的 local 的程式碼跟 scm 的程式碼是同步的
如果你要發布 1.0.0 版本的話
你的 pom.xml 裡要寫 1.0.0-SNAPSHOT
然後執行：

# deploy to snapshot repository
$ mvn clean deploy

你可以在 https://oss.sonatype.org/ 搜尋到
SNAPSHOT 版本測試都沒問題之後（當然你要先設定讓 Maven 能夠下載 SNAPSHOT 版本的 libraries）
就可以正式 release 了：

# cleanup for the release
$ mvn release:clean

# 要回答一些關於版本號的問題
# 它會自動幫你新增一個 tag 並且把 pom.xml 裡的 `<version>` 改成下個版本
$ mvn release:prepare

# deploy to staging repository
# 然後 Maven 會把上一步新增的 git tag 和 pom.xml 的變更直接 push 到 GitHub
$ mvn release:perform

Maven 會自動在 library 進到 staging repository 的時候把 -SNAPSHOT 字串拿掉

（第一次 release 才需要以下的動作）

然後你就可以在 https://oss.sonatype.org/#stagingRepositories
找到你剛剛 deploy 的 library
通常長得像是 wsvinta-1000（前面是 groupId）
要把它 close
然後再 release

除了第一次 release 要去 ticket 留言之外
之後 release 就會自動同步到 Maven Central Repository
不過通常會需要等一陣子才會在 Maven 上看到

ref:
http://dev.solita.fi/2014/10/22/publishing-to-maven-central-repository.html
http://lkrnac.net/blog/2014/03/deploy-to-maven-central/
http://kirang89.github.io/blog/2013/01/20/uploading-your-jar-to-maven-central/
http://superwang.me/2014/03/22/publish-your-library-to-maven-central-repository-part-1/
http://www.kongch.com/2013/05/deploy-to-central-repo/

如果你在 release 的過程中出了錯
要重新 release 的話
你得 revert 你的 git commit 到執行 mvn release:prepare 之前
然後再重新跑一次

Install

# on Mac OS X
$ brew install maven
$ brew install maven-completion

ref:
https://maven.apache.org/index.html

Commands

# create project: interactive mode
$ mvn archetype:generate \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DinteractiveMode=true

# create project: non-interactive mode
$ mvn archetype:generate \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DinteractiveMode=false \
-DgroupId=ws.vinta.pangu \
-DartifactId=pangu

# download dependencies
$ mvn dependency:copy-dependencies

# download dependencies to a specific directory
$ mvn dependency:copy-dependencies -DoutputDirectory=jars

# analyze unused dependencies
$ mvn dependency:analyze

$ mvn compile

$ mvn test

# run a specific class
$ mvn exec:java -Dexec.mainClass="pangu_example.App"

# package a JAR
$ mvn package

# 提交到 central repository 之前可以用這個來測試一下安裝有沒有問題
$ mvn clean install

build lifecycle
http://openhome.cc/Gossip/JUnit/BuildLifeCycle.html

• src/main/java 放置專案原始碼
• src/test/java 放置單元測試用原始碼
• src/main/resources 放置設定檔，例如 log4j.properties
• src/test/resources 放置測試用設定檔，如同測試程式本身不會被打包進 jar

Configuration

in pom.xml

放 per project 的設定

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.sonatype.oss</groupId>
    <artifactId>oss-parent</artifactId>
    <version>7</version>
  </parent>
  <groupId>ws.vinta</groupId>
  <artifactId>pangu</artifactId>
  <version>1.0.1-SNAPSHOT</version>
  <packaging>jar</packaging>
  <name>Pangu</name>
  <description>Paranoid text spacing for good readability, to insert whitespace between CJK (Chinese, Japanese, Korean), half-width English, digit and symbol characters automatically.</description>
  <url>https://github.com/vinta/pangu.java</url>
  <inceptionYear>2014</inceptionYear>
  <licenses>
    <license>
      <name>MIT License</name>
      <url>http://www.opensource.org/licenses/mit-license.php</url>
      <distribution>repo</distribution>
    </license>
  </licenses>
  <developers>
    <developer>
      <id>vinta</id>
      <name>Vinta</name>
      <email>[email protected]</email>
      <url>http://vinta.ws/</url>
    </developer>
  </developers>
  <scm>
    <connection>scm:git:[email protected]:vinta/pangu.java.git</connection>
    <developerConnection>scm:git:[email protected]:vinta/pangu.java.git</developerConnection>
    <url>[email protected]:vinta/pangu.java.git</url>
    <tag>HEAD</tag>
  </scm>
  <issueManagement>
    <system>GitHub Issues</system>
    <url>https://github.com/vinta/pangu.java/issues</url>
  </issueManagement>
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.11</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <distributionManagement>
    <snapshotRepository>
      <id>ossrh</id>
      <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </snapshotRepository>
    <repository>
      <id>ossrh</id>
      <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
    </repository>
  </distributionManagement>
  <profiles>
    <profile>
      <id>release</id>
      <build>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-gpg-plugin</artifactId>
            <version>1.5</version>
            <executions>
              <execution>
                <id>sign-artifacts</id>
                <phase>verify</phase>
                <goals>
                  <goal>sign</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.2</version>
        <configuration>
          <source>${maven.compile.source}</source>
          <target>${maven.compile.target}</target>
          <optimize>${maven.compile.optimize}</optimize>
          <encoding>UTF8</encoding>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <version>2.4</version>
        <executions>
          <execution>
            <id>attach-sources</id>
            <goals>
              <goal>jar-no-fork</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.10.1</version>
        <executions>
          <execution>
            <id>attach-javadocs</id>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.sonatype.plugins</groupId>
        <artifactId>nexus-staging-maven-plugin</artifactId>
        <version>1.6.5</version>
        <extensions>true</extensions>
        <configuration>
          <serverId>ossrh</serverId>
          <nexusUrl>https://oss.sonatype.org/</nexusUrl>
          <autoReleaseAfterClose>true</autoReleaseAfterClose>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-release-plugin</artifactId>
        <version>2.5.1</version>
        <configuration>
          <autoVersionSubmodules>true</autoVersionSubmodules>
          <useReleaseProfile>false</useReleaseProfile>
          <releaseProfiles>release</releaseProfiles>
          <goals>deploy</goals>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

ref:
http://maven.apache.org/pom.html
https://github.com/vinta/pangu.java/blob/master/pom.xml

Maven 的 groupId 基本上只是用來標示這個 artifact 屬於哪一個 group
基本上就是用你的 domain name 就好了
跟 Java 的 package 路徑沒有關係

in settings.xml

放 global 的設定

ref:
http://maven.apache.org/ref/3.2.3/maven-settings/settings.html

maven-source-plugin

maven-javadoc-plugin

How to attach source and javadoc artifacts?
http://maven.apache.org/plugin-developers/cookbook/attach-source-javadoc-artifacts.html

$ mvn source:jar
$ mvn javadoc:jar
# or
$ mvn package

Find packages

ref:
https://search.maven.org/
https://mvnrepository.com/

Issues

中文會是亂碼

<project>
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
</project>

ref:
http://maven.apache.org/general.html#encoding-warning

新增額外的 Maven Repositories

in pom.xml

<project>
    <repositories>
        <repository>
            <id>spark-packages</id>
            <name>Spark Packages Repository</name>
            <url>https://dl.bintray.com/spark-packages/maven/</url>
        </repository>
    </repositories>
</project>

ref:
https://maven.apache.org/guides/mini/guide-multiple-repositories.html

允許下載 SNAPSHOT 版本的 libraries

in ~/.m2/settings.xml

<settings>
  <profiles>
    <profile>
      <id>allow-snapshots</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <repositories>
        <repository>
          <id>ossrh-snapshots-repo</id>
          <url>https://oss.sonatype.org/content/repositories/snapshots</url>
          <releases>
            <enabled>false</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>
</settings>

你可以新增多個 snapshots repo 的來源

Could not find artifact com.sun:tools:jar

ref:
http://maven.apache.org/general.html#tools-jar-dependency