如何與全世界分享你的 library
TRANSCRIPT
如何與全世界分享你的 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