我參與了兩個接近100k+star的開源項目！聊聊開源項目貢獻指南

給 SkyWalking 以及 JavaGuide 項目貢獻后的總結(jié)

1. JavaGuide：https://github.com/Snailclimb/JavaGuide
2. SkyWalking：https://github.com/apache/skywalking

1. 本地開發(fā)

以 SkyWalking 舉例。在本地編譯源碼前，先查看相關(guān)的文檔：https://github.com/apache/skywalking/blob/v8.0.1/docs/en/guides/How-to-build.md 。大致了解后，我們就可以開始操作了。

1. 在 Github 上 fork 你想要貢獻的項目
2. 接著在本地拉取自己的項目：git clone --recurse-submodules https://github.com/$Name/skywalking.git

這是因為 SkyWalking 它包含了子倉庫，因此加入了 --recurse-submodules 參數(shù)，它可以把主倉庫和子倉庫源碼都同時拉取。

代碼拉到本地后，接著我們使用 idea 打開該項目。 但是可能我們網(wǎng)絡不夠給力或有“奇怪的力量”干擾，我們則需要改動一些配置以方便快速編譯。 對 maven 來說一般都是設置 maven 加速器，如果你拉的是 docker 相關(guān)，還需要配置 docker 容器阿里云地址加速。
而我們這里主要是設置 maven 阿里云鏡像以及 npm 設置淘寶鏡像。

1.1 設置 maven 加速

當你執(zhí)行 ./mvnw clean package -DskipTests 會發(fā)現(xiàn)以下很慢：

說明從 apache.snapshots 倉庫拉的很慢，因此我們對它使用鏡像倉庫代理，其中 mirrorOf 指定對某個倉庫鏡像做鏡像代理加速，建議 mirrorOf 做明確指定代碼的鏡像倉庫，避免直接使用 * 代理所有鏡像，導致你公司的私倉或其它倉庫出現(xiàn)拉不到包的情況：

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <mirrors>
        <mirror>
            <id>aliyun-apache.snapshotsid>
            <mirrorOf>apache.snapshotsmirrorOf>
            <name>aliyun-for-apahce.snapshotsname>
            <url>https://maven.aliyun.com/repository/apache-snapshotsurl>
        mirror>
    mirrors>
settings>

接著再執(zhí)行 ./mvnw clean package -DskipTests，就發(fā)現(xiàn)開始使用我們代理倉庫下載了：

同理對 center 倉庫也做代理：

<mirror>
    <id>aliyun-centerid>
    <mirrorOf>centermirrorOf>
    <name>aliyun-for-centername>
    <url>https://maven.aliyun.com/repository/publicurl>
mirror>

1.2 設置 npm 加速

因為有些項目里面包含前端項目（例如 Skywalking-ui），并且前端使用了 node 技術(shù)，則建議用淘寶鏡像加速，在這個案例中，如下 skywalking/apm-webapp 模塊中代碼如下：它使用了插件來執(zhí)行 npm 命令用于生成前端代碼，但是 npm 拉依賴包會比較慢，因此這里修改為淘寶鏡像地址：將 registry.npmjs.org 修改為：registry.npm.taobao.org。

1.3 編譯

還有其它的設置，例如在 SkyWalking 中需要設置 gRPC 為源碼包等，因為在官方的文檔有詳細步驟，就不做說明了。而 JavaGuide 項目不用編譯，打開即可，都是 md 類型的文檔。

2. 提 Issue

本地代碼編譯后，接著你可能會有兩個操作：

1. 你發(fā)現(xiàn)倉庫中有個地方的代碼寫的不好，而且你正好對這塊代碼所涉及的技術(shù)深有研究，那么你先不用直接寫代碼，而是先去對應的倉庫提 Issue，因為很多的倉庫，不會莫名其妙的接收用戶的 PR，需要先有對應的 Issue，便于作者了解需要改進的地方或知道你即將發(fā)起 PR 的緣由。Issue 一般會有模板并用 markdown 語法，只需要清楚的表達自己的問題描述就可以了。
2. 你發(fā)現(xiàn)倉庫已有了某個 Issue，而且你知道怎么解決該問題，以 JavaGuide 舉例，里面有時候會有些文字描述不當或文章有錯別字等這些錯誤，這對大家來說改進比較容易，因此你可以直接在本地新建分支做對應的改動。

2.1 Issue 藝術(shù)

Issue 本質(zhì)也類似于提問，因此需要清楚的表達你的疑惑并能讓別人看得懂。假如你是作者，你看到你的倉庫有如下兩個 Issue，你更加中意哪個？

但是很多項目都是要求英語交流，我都是先通過谷歌翻譯，接著看下翻譯之后的地方哪里表述有問題，再自己手動調(diào)整，其實表述大家都看得懂，還能順便學英語，例如我之前的 Issue：

2.2 Issue 的交流

一般 Issue 提出后，都會有相關(guān)的人做討論和交流。以 JavaGuide 舉例，里面有些 Issue 討論也可以學到很多的東西的，如下：

上圖可以看出作者對這類文章標記了 discuss 標簽，這樣你可以更加方便的搜索該標簽查找有價值的 Issue 了。

2.3 本地基本操作

這時候我們可以擼起袖子敲代碼了。定位你想要修改的代碼塊，你可以動手本地新建分支，修改，測試代碼。
注意：秉承一個分支改動一個功能點的理念。你改動代碼時，建議只改動 Issue 提及的相關(guān)的代碼，如果你想這個分支做多個改動，記得同步到 Issue 中。但是如果你發(fā)現(xiàn)了另一個改進點，但是這兩個改進點無任何聯(lián)系，建議再新建個 Issue，并再建個分支，在兩個分支分別做改動。這樣主要是如下理由：

1. 假如你在改動點 1 的代碼有問題，而在改動點 2 的代碼沒問題。但是由于它們是兩個獨立的分支，因此就不會互相影響，作者可以先 merge 你的分支 2（在公司也建議如下操作，一個分支一個改動點，方便出問題回滾）。

如果你本地做了多個提交，建議使用 git rebase 命令將多個提交合并為一個提交（僅建議）。

涉及到的基本命令：

1. 本地新建分支：git checkout -b feature/word_typo
2. 本地所有改動加入暫存區(qū)：git add .
3. 將暫存區(qū)提交：git commit -m "commit message"
4. 增加原倉庫上游地址：git remote add upstream https://github.com/apache/skywalking.git
5. 與遠程 master 分支合并：git merge upstream/master
6. 提交到自己的遠程倉庫：git push --set-upstream origin feature/word_typo

對第 4 步的解釋：因為你本地倉庫的遠程地址默認為你自己的遠程倉庫，但是你需要實時和源倉庫做同步更新，因此你額外需要保存源倉庫的地址，用于與源 master 合并，同步來自源倉庫的最新代碼。

3. 準備 PR

3.1 PR 通過

當你 push 當你的遠程倉庫后，此時你打開源倉庫，你會發(fā)現(xiàn)多了如下提示：我們點擊 Compare & pull request 按鈕，就會到 PR 界面了，如果作者配置了 PR 模板，我們跟著提示輸入即可，PR 界面主要做兩個事：

1. 查看你本次提交代碼與源倉庫主干的改動點。
2. 與作者討論此時 PR 的代碼，以及你此時 PR 的理由（在這里你可以使用 #111 來與你之前的 Issue 做關(guān)聯(lián)）。
3. 做對應的持續(xù)集成。

如果跟作者進行友好的交流討論后，沒什么問題，你的 PR 就會被合并接著在源倉庫中就會顯示當前的 PR 標題，以及你 PR 對應的 Issue。

3.2 PR 不通過

但是更多時候 PR 會不通過，一般大概有兩種：

1. 代碼審核不通過：你提交的 PR 代碼有問題，審核你代碼的作者會在 PR 討論跟你說哪里有問題，哪個地方需要改進，我們只需要跟著改動即可。
2. CI(持續(xù)集成) 有問題。這表明你的代碼沒問題，但是單元測試或持續(xù)集成驗證沒通過：在大型項目中，都會集成持續(xù)集成方案，如果你公司已經(jīng)在使用了 CI，那就比較熟練了，跟著 Docker 報錯日志仔細看看哪個地方有問題就行了。以 SkyWalking 舉例，它有個持續(xù)集成的測試步驟是這樣的：啟動 Docker 模擬項目啟動，模擬對應的請求，并與預期結(jié)果文件做對比，如果發(fā)現(xiàn)響應與預期結(jié)果文本對比異常，就會報錯不通過。這種情況我們可以通過 Github 的 Action 日志做排查。

這里建議了解如下：

1. Github Action：持續(xù)集成方案。公司一般會用 GitLab/Jenkins 多點。大概是監(jiān)聽你的代碼某個分支的提交/合并來做一系列的事，比如觸發(fā)某個腳本等。
2. Codecov：測試覆蓋率方案。公司一般會用 Sonar 比較多。
3. Checkstyle：如果你代碼沒問題，但是規(guī)則檢查沒通過，也會不允許合并。具體是注釋不規(guī)范還是代碼格式不規(guī)范查看具體的報錯即可。

4. 跟蹤項目進度

我們想實時跟進項目的進度或討論的話，可以有以下方式（國外的討論方式就不做列舉了）分別以 JavaGuide 和 SkyWalking 舉例：

1. RSS 訂閱 Issue 相關(guān)信息，例如：https://rsshub.app/github/issue/Snailclimb/JavaGuide 。最后兩個為變量，可以自由修改，規(guī)則為：UserName/RepositoryName
2. 加入群/關(guān)注 B 站，探（mo）討（yu）技術(shù)
3. 郵件訂閱，具體參考 dubbo：http://dubbo.apache.org/zh-cn/docs/developers/contributor-guide/mailing-list-subscription-guide_dev.html。適用于任何 apahce 項目，記得把 dubbo 改為具體項目即可（這里改為 skywalking）。
4. 參加線下活動：例如和某個社區(qū)伙伴面基、在活動行 APP 里面中關(guān)注項目線下宣傳什么的（而且阿里云相關(guān)的線下活動都有抽獎和零食）。

5. 額外

實際上，我們需要額外的插件來提高我們的效率。

Github 插件推薦兩個：

1. Octotree 用于可視化 Github 項目文件層級，你不用一個一個點進去就能看到全貌了。
2. GitZip 用于單獨下載某個文件/文件夾，不用為了下載某個文件，要把整個項目下載下來。

idea 插件推薦一個：Maven Help：分析某個 maven 項目的依賴關(guān)系，以及查找某個包被哪幾個依賴給同時依賴的，在復雜項目中，分析項目的依賴關(guān)系很方便。

其實關(guān)注 JavaGuide 微信公眾號的都會了解 JavaGuide 項目，但是項目貢獻的人很少，也有很多人很久沒有再繼續(xù)貢獻和討論了。這篇文章只是做拋磚引玉，希望大家能能了解 JavaGuide  原項目，當然能參與進來貢獻那肯定是最好的。畢竟 JavaGuide 是我貢獻的開源項目里堅持最久的~希望它能一直活力四射~