1.
如何與全世界分享你的 library
Kewang

2.
Who I am
● 王慕羣 Kewang
● Java / Node.js / AngularJS
● HBase / SQL-like
● Git / DevOps
●
熱愛開源
GitHubGitHub kewangkewang
LinkedinLinkedin kewangtwkewangtw
SlideShareSlideShare kewangkewang
GmailGmail cpckewangcpckewang
FacebookFacebook Kewang 的資訊進化論Kewang 的資訊進化論 HadoopConHadoopCon '14 '15'14 '15
MOPCONMOPCON '14'14
JCConfJCConf '16'16
DevOpsDays TaipeiDevOpsDays Taipei '17'17

3.
What Mitake is
三竹資訊
● Qmi：企業內部即時通訊軟體
●
全國最大的企業簡訊平台
● 市佔近 100% 的行動下單
● 市佔近 70% 的行動銀行
●
企業內部應用、產壽險、金融相關政府機關
● MicroCoin 、兌彩券、台灣匯率、三竹小股王、行動股市
GitHubGitHub mitaketwmitaketw

4.
4
Agenda
● How to import library ?
● How to publish library ?
● SemVer,Git, Changelog

5.
5
How to import library ?

6.
6
Maven
<dependencies>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.6</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
</dependencies>

7.
7
Gradle
compile group: 'org.apache.commons',
name: 'commons-lang3',
Version: '3.6'
compile group: 'junit',
name: 'junit',
Version: '3.8.1'

8.
8
https://repo1.maven.org/maven2/

9.
9
https://repo1.maven.org/maven2/

10.
10
How to publish library ?

11.
11
Maven 上的那些 Jar 是如何鍊成的

12.
12
Maven 上的那些 Jar 是如何鍊成的

13.
13
library 命名原則

14.
14
library 命名原則
● groupId ：使用與 Java package 相同的命名原則，
為反轉後的網域名稱
– www.springframework.org org.springframework→
– oness.sf.net net.sf.oness→
– github.com/yourusername com.github.yourusername→

15.
15
library 命名原則
● groupId ：使用與 Java package 相同的命名原則，
為反轉後的網域名稱
– www.springframework.org org.springframework→
– oness.sf.net net.sf.oness→
– github.com/yourusername com.github.yourusername→
● artifactId ：專案名稱，一般可使用 - 做為分隔符
號
– maven-core, commons-math

16.
16
library 命名原則
● groupId ：使用與 Java package 相同的命名原則，
為反轉後的網域名稱
– www.springframework.org org.springframework→
– oness.sf.net net.sf.oness→
– github.com/yourusername com.github.yourusername→
● artifactId ：專案名稱，一般可使用 - 做為分隔符
號
– maven-core, commons-math
● version ：使用 SemVer
– 2.3.1, 1.7.0

17.
17
各種不同的 Maven repo

18.
18
各種不同的 Maven repo
● bintray ：可存放單一使用者 library 的公開 repo

19.
19
各種不同的 Maven repo
● bintray ：可存放單一使用者 library 的公開 repo
● jCenter ：由 bintray 維護的公開 repo ，使用者可
將自己的 bintray repo 同步到 jCenter

20.
20
各種不同的 Maven repo
● bintray ：可存放單一使用者 library 的公開 repo
● jCenter ：由 bintray 維護的公開 repo ，使用者可
將自己的 bintray repo 同步到 jCenter
● Maven Central ：由 Sonatype 維護的公開 repo ，
為 Maven 預設 repo ，使用者可將自己的 bintray
repo 同步到 Maven Central

21.
21
Maven Central VS jCenter

22.
22
Maven Central VS jCenter
● Maven Central 對開發者不友善

23.
23
Maven Central VS jCenter
● Maven Central 對開發者不友善
● 因為安全性問題， Android Studio 決定把預設
repo 改為 jCenter

24.
24
Maven Central VS jCenter
● Maven Central 對開發者不友善
● 因為安全性問題， Android Studio 決定把預設
repo 改為 jCenter
● jCenter 有 CDN ，下載更快

25.
25
Maven Central VS jCenter
● Maven Central 對開發者不友善
● 因為安全性問題， Android Studio 決定把預設
repo 改為 jCenter
● jCenter 有 CDN ，下載更快
● jCenter 是 Maven Central 的母集合

26.
26
注意事項 - 證明 groupId 的擁有權 1

27.
27
注意事項 - 證明 groupId 的擁有權 1
● 以三竹為例，英文名為 mitake ，網域名稱為
mitake.com.tw

28.
28
注意事項 - 證明 groupId 的擁有權 1
● 以三竹為例，英文名為 mitake ，網域名稱為
mitake.com.tw
– 不可使用 mitake 為 groupId

29.
29
注意事項 - 證明 groupId 的擁有權 1
● 以三竹為例，英文名為 mitake ，網域名稱為
mitake.com.tw
– 不可使用 mitake 為 groupId
– 可使用 tw.com.mitake 為 groupId ，但須證明有
mitake.com.tw 的使用權，可使用
<USERNAME>@mitake.com.tw 寄信佐證

30.
30
注意事項 - 證明 groupId 的擁有權 2

31.
31
注意事項 - 證明 groupId 的擁有權 2
● 以 logpush 為例，網域名稱為 logpush.io

32.
32
注意事項 - 證明 groupId 的擁有權 2
● 以 logpush 為例，網域名稱為 logpush.io
– 不可使用 logpush 為 groupId

33.
33
注意事項 - 證明 groupId 的擁有權 2
● 以 logpush 為例，網域名稱為 logpush.io
– 不可使用 logpush 為 groupId
– 可使用 io.logpush 為 groupId ，但須證明為 logpush.io
的擁有者，可附上網域申請資料佐證

34.
34
How to publish library ?

35.
35
How to publish library ?
easily

36.
36
JitPack

37.
37
JitPack
● 可將 Git 上的程式碼發佈為 JVM 及 Android
library
● 可編譯成 jar 或 aar
● 可直接整合 GitHub 上的 Release / tag 功能

38.
38
Publish @ Maven
<groupId>com.github.kewang</groupId>
<artifactId>jitpack-maven</artifactId>
<version>0.1.0-SNAPSHOT</version>
<packaging>jar</packaging>
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>

39.
39
Publish @ Gradle
group 'com.github.kewang'
version '0.1.0-SNAPSHOT'
apply plugin: "maven"
repositories {
maven { url "https://jitpack.io" }
}

40.
40
Version 定義

41.
41
Version 定義
● Tag ： push 後， JitPack 會自動 build source
code ，使用者可以直接使用

42.
42
Version 定義
● Tag ： push 後， JitPack 會自動 build source
code ，使用者可以直接使用
● SHA1 ：類似 Tag ，但不會自動 build 。因為
JitPack 無法得知是否每個 commit 都要 build ，只
會在第一次引用時才去 build

43.
43
Version 定義
● Tag ： push 後， JitPack 會自動 build source
code ，使用者可以直接使用
● SHA1 ：類似 Tag ，但不會自動 build 。因為
JitPack 無法得知是否每個 commit 都要 build ，只
會在第一次引用時才去 build
● branch-SNAPSHOT ：把 Git 的 HEAD 概念轉為
Maven 的 SNAPSHOT ，與 SHA1 一樣，第一次使
用時才會去 build

44.
44
Live DEMO

45.
45
More JitPack
●
提供下載統計
● 提供 Badge
● 提供 private repo
● 提供 Javadoc hosting
● 支援 Bitbucket 及 GitLab
● 支援 Gradle dynamic version
● 支援 custom domain
● 可以整合 build.log 與 GitHub Webhooks
● 可以分享 library 但不分享 source code

46.
46
SemVer,Git, Changelog

47.
47
SemVer ：主版號 . 次版號 . 修訂版號

48.
48
SemVer ：主版號 . 次版號 . 修訂版號
● 主版號：不相容的 API 修改

49.
49
SemVer ：主版號 . 次版號 . 修訂版號
● 主版號：不相容的 API 修改
●
次版號：向下相容的功能性新增

50.
50
SemVer ：主版號 . 次版號 . 修訂版號
● 主版號：不相容的 API 修改
●
次版號：向下相容的功能性新增
●
修訂版號：向下相容的問題修正

51.
51
SemVer ：主版號 . 次版號 . 修訂版號
● 主版號：不相容的 API 修改
●
次版號：向下相容的功能性新增
●
修訂版號：向下相容的問題修正
● 先行版號及版本編譯資訊可以加到「主版號 . 次
版號 . 修訂版號」後面作為延伸

52.
52
SemVer ：主版號 . 次版號 . 修訂版號
● 主版號：不相容的 API 修改
●
次版號：向下相容的功能性新增
●
修訂版號：向下相容的問題修正
● 先行版號及版本編譯資訊可以加到「主版號 . 次
版號 . 修訂版號」後面作為延伸
● 以 0.1.0 作為初始化版本，並在每次發行時遞增
次版號

53.
53
SemVer FAQ

54.
54
SemVer FAQ
● 1.0.0 版的定義：用於正式環境、穩定的 API 被使
用者依賴、擔心向下相容

55.
55
SemVer FAQ
● 1.0.0 版的定義：用於正式環境、穩定的 API 被使
用者依賴、擔心向下相容
●
主版號為零是為了快速開發，如果每天都在改變
API ，那麼主版號應該仍然為零

56.
56
SemVer FAQ
● 1.0.0 版的定義：用於正式環境、穩定的 API 被使
用者依賴、擔心向下相容
●
主版號為零是為了快速開發，如果每天都在改變
API ，那麼主版號應該仍然為零
●
萬一不小心把一個不相容的改版當成了次版號發
行，必須發行新的次版號更正這個問題

57.
57
Git

58.
58
Git
● library 不會自動更新

59.
59
Git
● library 不會自動更新
●
各種版本被引用

60.
60
Git
● library 不會自動更新
●
各種版本被引用
●
每個次版號都必須要開新分支

61.
61
Git
● library 不會自動更新
●
各種版本被引用
●
每個次版號都必須要開新分支
●
重大變更時需增加主版號，並確認是否可相容舊
主版號

62.
62
Changelog 原則

63.
63
Changelog 原則
●
日誌是寫給「人」看的

64.
64
Changelog 原則
●
日誌是寫給「人」看的
●
每個版本都應該有獨立的進入點

65.
65
Changelog 原則
●
日誌是寫給「人」看的
●
每個版本都應該有獨立的進入點
●
相同類型的變更應分組放置

66.
66
Changelog 原則
●
日誌是寫給「人」看的
●
每個版本都應該有獨立的進入點
●
相同類型的變更應分組放置
●
版本與章節應「可連結化」

67.
67
Changelog 原則
●
日誌是寫給「人」看的
●
每個版本都應該有獨立的進入點
●
相同類型的變更應分組放置
●
版本與章節應「可連結化」
●
新版本寫在最前面

68.
68
Changelog 原則
●
日誌是寫給「人」看的
●
每個版本都應該有獨立的進入點
●
相同類型的變更應分組放置
●
版本與章節應「可連結化」
●
新版本寫在最前面
●
每個版本都要註記發佈日期

69.
69
Changelog 原則
●
日誌是寫給「人」看的
●
每個版本都應該有獨立的進入點
●
相同類型的變更應分組放置
●
版本與章節應「可連結化」
●
新版本寫在最前面
●
每個版本都要註記發佈日期
● 版本命名應遵守 SemVer

70.
70
糟糕的 Changelog

71.
71
糟糕的 Changelog
● 直接使用 git log

72.
72
糟糕的 Changelog
● 直接使用 git log
● 忽略 deprecation

73.
73
糟糕的 Changelog
● 直接使用 git log
● 忽略 deprecation
●
容易混淆的日期格式

74.
74
References
● OSSRH Guide
● How to distribute your own Android library throug
h jCenter and Maven Central from Android Studio
● Choosing your Coordinates
● Keep a Changelog
● SemVer

75.
75