Upload your Java Artifacts to Maven Central Repository

Upload your Java Artifacts to Maven Central Repository

你需要:

  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 之前
然後再重新跑一次

Maven: The De Facto Build Tool for JVM Projects

Maven: The De Facto Build Tool for JVM Projects

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

Debug your Django project

Debug your Django project

How to debug in Django, the good way
http://stackoverflow.com/questions/1118183/how-to-debug-in-django-the-good-way

pdb or ipdb

ref:
ipdb: Interactive Python Debugger with IPython
https://vinta.ws/code/ipdb-interactive-python-debugger-with-ipython.html

django-pdb

$ pip install django-pdb
$ ./manage.py runserver 0.0.0.0:8000 --ipdb

ref:
https://github.com/tomchristie/django-pdb

Templatetags

from django import template
register = template.Library()

@register.filter 
def ipdb(element):
    import ipdb; ipdb.set_trace()
    return element

ref:
http://stackoverflow.com/questions/1118183/how-to-debug-in-django-the-good-way

django-extensions

$ pip install django-extensions
$ ./manage.py runserver_plus 0.0.0.0:8000

ref:
https://github.com/django-extensions/django-extensions

django-devserver

$ pip install django-devserver
$ ./manage.py runserver 0.0.0.0:8000 --werkzeug

上面這兩個 plugins 都是用 Werkzeug 的 interactive debugger
跟 Flask 用的那個一樣
你可以直接在瀏覽器的 Traceback 畫面按那個 terminal 圖示進入互動 debug 模式

ref:
https://github.com/dcramer/django-devserver

django-debug-toolbar

$ pip install django-debug-toolbar

ref:
https://github.com/django-debug-toolbar/django-debug-toolbar

coverage.py: Python code coverage

coverage.py: Python code coverage

coveralls.io 跑 python project 的覆蓋率就是用 coverage.py
nose 也是用 coverage.py
基本上 Python 社群幾乎都是用這個

ref:
http://nedbatchelder.com/code/coverage/
http://www.cnblogs.com/coderzh/archive/2009/12/01/1614874.html

Install

$ pip install coverage

Configuration

in .coveragerc

[run]
branch = True
source = email_confirm_la
omit =
    email_confirm_la/migrations/*
    email_confirm_la/south_migrations/*
    email_confirm_la/tests/*

[run] 底下的 include 和 omit 是用來指定 filename pattern
而 source 是用來指定 package 或目錄

omit 是「忽略」的意思

ref:
http://nedbatchelder.com/code/coverage/config.html

Usage

# 會自動套用當前目錄下的 .coveragerc
$ coverage run setup.py test
$ coverage report
$ coverage html

# 默認會一併測試所有包含第三方 lib 在內的 Python 程式碼(如果你沒有寫 .coveragerc 的話)
$ coverage run test.py

# 你可以用 --source 指定只測試某個 packages 或目錄
$ coverage run --source=haul setup.py test
$ coverage run --source=haul tests/test.py
$ coverage run --source=. manage.py test

# show report in terminal
$ coverage report

# generate html report in the same dir
$ coverage html

ref:
http://nedbatchelder.com/code/coverage/cmd.html
http://nedbatchelder.com/code/coverage/source.html

Usage with nose

$ pip install nose nose-cov

# output terminal
$ nosetests --with-cov --cov haul tests/

# output html
$ nosetests --with-cov --cov-report html --cov haul tests/ 
Travis-CI for Python: a .travis.yml example

Travis-CI for Python: a .travis.yml example

Configuration

in .travis.yml

language: python

# 多個 env 要寫在同一行
env:
  - DPS_ENV=test OTHER_ENV=whatever
  - DPS_ENV=development OTHER_ENV=whatever

python:
  - "2.7"
  - "3.3"

before_install:
  - sudo apt-get update -qq
  - sudo apt-get install -qq libxml2-dev libxslt1-dev

install:
  - pip install -r requirements_test.txt --use-mirrors

script:
  - coverage run --source=haul setup.py test

notifications:
  email:
    - [email protected]

after_success:
  - coveralls

要注意的是多個 environment variables 要寫在同一行
否則會被當成多個環境
每個環境都會跑一次 CI

ref:
http://docs.travis-ci.com/user/ci-environment/
http://docs.travis-ci.com/user/build-configuration/
http://docs.travis-ci.com/user/languages/python/
http://docs.travis-ci.com/user/database-setup/

in .coveralls.yml

如果是 public repo 的話,不需要特別設定什麼

ref:
https://coveralls.io/docs/python
https://github.com/coagulant/coveralls-python