如何與全世界分享你的 library

Kewang

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

What Mitake is

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

GitHubGitHub mitaketwmitaketw

4

Agenda

● How to import library ?● How to publish library ?● SemVer, Git, Changelog

5

How to import library ?

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

Gradle

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

8

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

9

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

10

How to publish library ?

11

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

12

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

13

library 命名原則

14

library 命名原則● groupId ：使用與 Java package 相同的命名原則，為反轉後的網域名稱

– www.springframework.org org.springframework→– oness.sf.net net.sf.oness→– github.com/yourusername com.github.yourusername→

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

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

各種不同的 Maven repo

18

各種不同的 Maven repo

● bintray ：可存放單一使用者 library 的公開 repo

19

各種不同的 Maven repo

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

20

各種不同的 Maven repo

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

repo 同步到 Maven Central

21

Maven Central VS jCenter

22

Maven Central VS jCenter

● Maven Central 對開發者不友善

23

Maven Central VS jCenter

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

repo 改為 jCenter

24

Maven Central VS jCenter

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

repo 改為 jCenter● jCenter 有 CDN ，下載更快

25

Maven Central VS jCenter

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

repo 改為 jCenter● jCenter 有 CDN ，下載更快● jCenter 是 Maven Central 的母集合

26

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

27

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

● 以三竹為例，英文名為 mitake ，網域名稱為mitake.com.tw

28

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

● 以三竹為例，英文名為 mitake ，網域名稱為mitake.com.tw– 不可使用 mitake 為 groupId

29

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

● 以三竹為例，英文名為 mitake ，網域名稱為mitake.com.tw– 不可使用 mitake 為 groupId– 可使用 tw.com.mitake 為 groupId ，但須證明有

mitake.com.tw 的使用權，可使用<USERNAME>@mitake.com.tw 寄信佐證

30

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

31

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

● 以 logpush 為例，網域名稱為 logpush.io

32

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

● 以 logpush 為例，網域名稱為 logpush.io– 不可使用 logpush 為 groupId

33

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

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

34

How to publish library ?

35

How to publish library ?easily

36

JitPack

37

JitPack

● 可將 Git 上的程式碼發佈為 JVM 及 Android library

● 可編譯成 jar 或 aar● 可直接整合 GitHub 上的 Release / tag 功能

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

Publish @ Gradle

group 'com.github.kewang'version '0.1.0-SNAPSHOT'

apply plugin: "maven"

repositories { maven { url "https://jitpack.io" }}

40

Version 定義

41

Version 定義● Tag ： push 後， JitPack 會自動 build source

code ，使用者可以直接使用

42

Version 定義● Tag ： push 後， JitPack 會自動 build source

code ，使用者可以直接使用● SHA1 ：類似 Tag ，但不會自動 build 。因為

JitPack 無法得知是否每個 commit 都要 build ，只會在第一次引用時才去 build

43

Version 定義● Tag ： push 後， JitPack 會自動 build source

code ，使用者可以直接使用● SHA1 ：類似 Tag ，但不會自動 build 。因為

JitPack 無法得知是否每個 commit 都要 build ，只會在第一次引用時才去 build● branch-SNAPSHOT ：把 Git 的 HEAD 概念轉為

Maven 的 SNAPSHOT ，與 SHA1 一樣，第一次使用時才會去 build

44

Live DEMO

45

More JitPack

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

46

SemVer, Git, Changelog

47

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

48

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

49

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

50

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

51

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

52

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

53

SemVer FAQ

54

SemVer FAQ

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

55

SemVer FAQ

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

API ，那麼主版號應該仍然為零

56

SemVer FAQ

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

API ，那麼主版號應該仍然為零● 萬一不小心把一個不相容的改版當成了次版號發行，必須發行新的次版號更正這個問題

57

Git

58

Git

● library 不會自動更新

59

Git

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

60

Git

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

61

Git

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

62

Changelog 原則

63

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

64

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

65

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

66

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

67

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

68

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

69

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

70

糟糕的 Changelog

71

糟糕的 Changelog

● 直接使用 git log

72

糟糕的 Changelog

● 直接使用 git log● 忽略 deprecation

73

糟糕的 Changelog

● 直接使用 git log● 忽略 deprecation● 容易混淆的日期格式

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