首頁(yè)人工智能技術(shù)資訊正文

如何成為頂級(jí)開源項(xiàng)目的貢獻(xiàn)者

更新時(shí)間:2020-09-07 來源:黑馬程序員 瀏覽量:

概述

對(duì)于程序員來講,成為頂級(jí)開源項(xiàng)目的貢獻(xiàn)者是一件有意義的事,當(dāng)然,這也絕非易事。如果你正從事人工智能有關(guān)的工作,那么你一定了解諸如Google Tensorflow,F(xiàn)acebook Pytorch這樣的開源項(xiàng)目。下面我們就說一說如何成為這些頂級(jí)的開源項(xiàng)目的Contributor。

準(zhǔn)備

1.首先你必須成為github的使用者,并已經(jīng)熟悉了github上托管代碼的基本邏輯。

2.對(duì)于頂級(jí)的開源項(xiàng)目,一般需要你去簽署一份Contributor License Agreement(簡(jiǎn)稱CLA),例如Tensorflow項(xiàng)目,個(gè)人簽署TF individual CLA,公司簽署TF corporate CLA,Pytorch中的部分項(xiàng)目則需要簽署Facebook CLA,這樣你的代碼才允許被接收。

3.讓你編寫的代碼風(fēng)格更規(guī)范,一般的開源項(xiàng)目都要求為Google Python Style,即使是Pytorch都是遵循該規(guī)范,更不要說Google自家的Tensorflow了。

4.你貢獻(xiàn)的代碼往往由類或者函數(shù)構(gòu)成(文檔貢獻(xiàn)除外),因此你需要單元測(cè)試程序,它和代碼注釋一樣,是代碼共享過程中必不可少的一部分。沒有它,即使你的代碼正確無(wú)誤也不會(huì)被merge,最終還是會(huì)被要求提供單元測(cè)試腳本。

5.很多開源項(xiàng)目要求你的每個(gè)py腳本都要以許可證書開頭,比如Tensorflow,這是它的python許可證書示例: Python license example,當(dāng)然,這很簡(jiǎn)單。

# Copyright 2015 The TensorFlow Authors. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# =============================================================================

工具

接下來我們將介紹相關(guān)工具的使用,它能夠有效的幫助我們來完成貢獻(xiàn)前的準(zhǔn)備工作,比如:代碼規(guī)范和單元測(cè)試等。

代碼規(guī)范工具

為了滿足代碼滿足Google Style的要求,我們首先需要一個(gè)代碼規(guī)范檢測(cè)工具,這里我們使用官方推薦的pylint。

安裝:

pip install pylint

使用:
# 使用pylint檢測(cè)腳本代碼,默認(rèn)將按照PEP8標(biāo)準(zhǔn)
# 這里我們需要指定配置文件,即按照Google Style標(biāo)準(zhǔn)
# myfile.py代表你寫好的python腳本文件
pylint --rcfile=pylintrc myfile.py

pylintrc內(nèi)容請(qǐng)參照: pylintrc

又因?yàn)槲覀兂跏紝懙拇a往往隨意性過強(qiáng),可能直接用pylint需要修改的地方太多,可能對(duì)你幼小的心靈造成重創(chuàng),因此,這里也帶來很多開源項(xiàng)目推薦的另外一款工具:black,它能夠直接幫你修改代碼中出現(xiàn)的基本問題(仍然存在很多問題無(wú)法被判定,需要使用pylint檢測(cè))。

安裝:

pip install black


使用:
# 這里的-l代表代碼的每行最大長(zhǎng)度
# 默認(rèn)是88,但是Google Style要求為80
# 因此這里指定為80
black myfile.py -l 80


代碼樣式示例:

def my_op(tensor_in, other_tensor_in, my_param, other_param=0.5,
          output_collections=(), name=None):
  """My operation that adds two tensors with given coefficients.

  Args:
    tensor_in: `Tensor`, input tensor.
    other_tensor_in: `Tensor`, same shape as `tensor_in`, other input tensor.
    my_param: `float`, coefficient for `tensor_in`.
    other_param: `float`, coefficient for `other_tensor_in`.
    output_collections: `tuple` of `string`s, name of the collection to
                        collect result of this op.
    name: `string`, name of the operation.

  Returns:
    `Tensor` of same shape as `tensor_in`, sum of input values with coefficients.

  Example:
    >>> my_op([1., 2.], [3., 4.], my_param=0.5, other_param=0.6,
              output_collections=['MY_OPS'], name='add_t1t2')
    [2.3, 3.4]
  """
  with tf.name_scope(name or "my_op"):
    tensor_in = tf.convert_to_tensor(tensor_in)
    other_tensor_in = tf.convert_to_tensor(other_tensor_in)
    result = my_param * tensor_in + other_param * other_tensor_in
    tf.add_to_collection(output_collections, result)
    return result
output = my_op(t1, t2, my_param=0.5, other_param=0.6,
               output_collections=['MY_OPS'], name='add_t1t2')


單元測(cè)試工具

·單元測(cè)試對(duì)于團(tuán)隊(duì)開發(fā)十分重要,是檢驗(yàn)代碼質(zhì)量的重要依據(jù),因此你的每一份完整的代碼都要配備單元測(cè)試腳本。這里我們使用python主流的單元測(cè)試工具unittest。

· 安裝:

pip install unittest


使用: 這里只去演示核心的使用方法,更具體的內(nèi)容請(qǐng)參照unittest文檔

# 導(dǎo)入unittest工具包
import unittest

# 我們首先要建立一個(gè)測(cè)試類,它將包含你所有需要進(jìn)行測(cè)試的函數(shù)
# 這個(gè)類不使用__init__(self),但可以使用setUp(self)來定義公有部分
# 它需要繼承unittest.TestCase, 類名往往也建議以Test開頭
class TestStringMethods(unittest.TestCase):
    # 類的里面依次是你需要進(jìn)行測(cè)試的函數(shù)
    # 這些函數(shù)建議以test_開頭
    # 這些函數(shù)一般情況不設(shè)置參數(shù),而是直接在函數(shù)中具體化需要的參數(shù)
    # 當(dāng)然你也可以設(shè)置原始的參數(shù),然后在外部具體化參數(shù)并調(diào)用該函數(shù)
    # 在測(cè)試函數(shù)中必須存在assert...來斷定測(cè)試結(jié)果
    # 常用的assert...包括: assertEqual, assertTrue, assertFalse,
    # assertRaises, assertIn, assertNotIn, assertIs, assertIsNot...
    def test_upper(self,):
        # 使用assertEqual判斷兩個(gè)字符串是否相等
        self.assertEqual(
            "foo".upper(), "FOO",
        )

    def test_isupper(self,):
        # 使用assertTrue/False斷定條件為真/假
        self.assertTrue("FOO".isupper())
        self.assertFalse("Foo".isupper())

    def test_split(self,):
        # 設(shè)定任意輸入
        s = "hello world"
        # 使用assertIn斷定列表包含關(guān)系
        self.assertIn(
            s.split(), [["hello", "world"]],
        )
        # 注意:這里with self.assertRaises來斷定異常
        with self.assertRaises(TypeError):
            s.split("asd")


# 這里是主函數(shù),如果使用python運(yùn)行該腳本測(cè)試,則必須存在
# 如果使用pytest(后面會(huì)介紹),則可以省略
if __name__ == "__main__":
    # 使用unittest.main運(yùn)行所有繼承unittest.TestCase的類
    unittest.main()

裝飾器的使用: unittest最常使用方法之一就是類/函數(shù)的裝飾器。

# 對(duì)于一些特殊需要強(qiáng)制跳過的測(cè)試的類/函數(shù)使用下方裝飾器,但你必須說明原因
# @unittest.skip("長(zhǎng)得太帥,不需要測(cè)試,給我跳過!")

# 如果條件為真,則該測(cè)試被強(qiáng)制跳過。比如:檢測(cè)GPU是否可用
# @unittest.skipIf(TEST_CUDA, "CUDA available")

# 除非條件為真,否則該測(cè)試被強(qiáng)制跳過。比如: 檢測(cè)某些依賴包是否安裝
# @unittest.skipUnless(has_unittest, "unittest dependencies are not installed")

# 函數(shù)異常測(cè)試的表達(dá)方式,函數(shù)出現(xiàn)異常則測(cè)試通過,比之前說的內(nèi)部異常粒度更大
# @unittest.expectedFailure

import torch
try:
    import unittest
except ImportError:
    has_unittest = False
else:
    has_unittest = True

if torch.cuda.is_available():
    TEST_CUDA = True
else:
    TEST_CUDA = False

# 條件為真,不跳過
@unittest.skipUnless(has_unittest, "unittest dependencies are not installed")
# 條件為真,跳過;條件為假,不跳過
@unittest.skipIf(TEST_CUDA, "CUDA available")
class TestStringMethods(unittest.TestCase):
    def test_upper(self,):
        self.assertEqual(
            "foo".upper(), "FOO",
        )
    @unittest.skip("長(zhǎng)得太帥,不需要測(cè)試,給我跳過!")
    def test_isupper(self,):
        self.assertTrue("FOO".isupper())
        self.assertFalse("Foo".isupper())

    @unittest.expectedFailure
    def test_split(self,):
        s = "hello world"
        self.assertIn(
            s.split(), [["hello", "world"]],
        )
        # 這里預(yù)計(jì)拋出異常,但實(shí)際沒有異常,本質(zhì)上這也算一種異常
        # 可以使用@unittest.expectedFailure
        with self.assertRaises(TypeError):
            s.split("ZMZ")


if __name__ == "__main__":
    unittest.main()


運(yùn)行你的測(cè)試腳本:

# 建議使用pytest執(zhí)行測(cè)試腳本,你的python中往往自帶這個(gè)工具包
# 這時(shí)你不必寫下主函數(shù),并且他的輸出形式更美觀
pytest test_myfile.py


輸出效果:

======================== test session starts =========================
platform linux -- Python 3.7.3, pytest-5.0.1, py-1.8.0, pluggy-0.12.0
rootdir: /root
plugins: remotedata-0.3.1, celery-4.3.0, doctestplus-0.3.0, arraydiff-0.3, openfiles-0.3.2
collected 3 items

test_myfile.py sx.                                             [100%]

=========== 1 passed, 1 skipped, 1 xfailed in 0.34 seconds ===========

真實(shí)單元測(cè)試腳本請(qǐng)參考Pytorch Tests和Tensorflow Tests

過程

在準(zhǔn)備成為貢獻(xiàn)者之前,要確保你已經(jīng)能夠熟練使用該項(xiàng)目。進(jìn)而明確你要貢獻(xiàn)源碼的類型,是Fix Bug還是Implement New Feature(實(shí)現(xiàn)新特性)。當(dāng)然,對(duì)一個(gè)新手貢獻(xiàn)者來講,F(xiàn)ix Bug是你的不二選擇。除非你已經(jīng)通過自己的實(shí)踐,明確了要做貢獻(xiàn)的具體內(nèi)容,否則,建議你需要遵循以下步驟:

第一步:

從開源項(xiàng)目的Github Issues中尋找open的問題,這里是Tensorflow Issues, Pytorch Issues,仔細(xì)閱讀大家提出的問題,這將幫你在尋找問題上節(jié)約大量時(shí)間,同時(shí)你可以在討論區(qū)看到有關(guān)技術(shù)的討論或已經(jīng)提交的PR,進(jìn)一步明確自己是否應(yīng)該參與該問題的解決。(有很多開源項(xiàng)目的issue會(huì)帶有"contributions welcome"的標(biāo)簽,可以優(yōu)先看一看。)

第二步:

當(dāng)你明確了自己要解決的問題,在正式寫代碼之前,你需要fork這個(gè)開源項(xiàng)目到你自己的Github倉(cāng)庫(kù),然后再將該倉(cāng)庫(kù)clone到自己指定的服務(wù)器上,這樣最后你才可以提交PR。

# 例如:
git clone https://github.com/AITutorials/tensorflow.git

到這里你可以通過git remote -v發(fā)現(xiàn)我們只與自己遠(yuǎn)程倉(cāng)庫(kù)進(jìn)行了連接(origin/master)。

此時(shí)我們還需要與開源項(xiàng)目的遠(yuǎn)程倉(cāng)庫(kù)建立連接(upstream/master)

# 以tensorflow為例建立連接
git remote add upstream https://github.com/tensorflow/tensorflow.git

# 查看到upstream
git remote -v

然后你就需要建立一個(gè)自己的分支,當(dāng)然,你可以先查看一下遠(yuǎn)程的分支情況

# 查看遠(yuǎn)程分支
git branch -a

# 創(chuàng)建自己的遠(yuǎn)程分支cnsync
git checkout -b cnsync

第三步:

通過第二步你已經(jīng)拿到了項(xiàng)目的源碼并創(chuàng)建了自己分支,這時(shí)就要開始你的表演,coding + review,你之前準(zhǔn)備的代碼規(guī)范工具和單元測(cè)試工具將派上用場(chǎng)。

第四步:

提交代碼你的代碼并在github中創(chuàng)建一個(gè)PR。

# 把內(nèi)容添加到暫存區(qū)
git add .

# 提交更改的內(nèi)容
git commit -m "添加你的改變說明"

# push到自己的遠(yuǎn)程倉(cāng)庫(kù)
git push origin cnsync

注意:這里雖然你只push到了自己的遠(yuǎn)程倉(cāng)庫(kù),但其實(shí)你的遠(yuǎn)程倉(cāng)庫(kù)和源項(xiàng)目的倉(cāng)庫(kù)是連接的。也就是說,此時(shí)你可以通過操作自己的遠(yuǎn)程倉(cāng)庫(kù)決定是否將創(chuàng)建一個(gè)源項(xiàng)目的PR(這些過程可以在你剛剛fork的項(xiàng)目頁(yè)面中實(shí)現(xiàn),包括填寫PR的title和comment,有時(shí)你也需要在title中添加一個(gè)標(biāo)記,如[Draft]/[WIP]/[RFR]等等)。

第五步:

耐心的等待,如果你是PR是一個(gè)Ready For Review的狀態(tài),它將很快進(jìn)入自動(dòng)化測(cè)試的流程以及評(píng)委會(huì)的介入,不久后你將收到一些反饋,你的代碼方案可能被采納,可能需要更多的修改或測(cè)試。

結(jié)語(yǔ)

最終,經(jīng)過不斷地磨練,你將成為一名頂級(jí)開源項(xiàng)目的貢獻(xiàn)者,所以,加油吧少年!


猜你喜歡:

Bert算法:語(yǔ)言模型-BERT詳細(xì)介紹

孤立森林算法介紹,這次終于看懂了!

分享到:
在線咨詢 我要報(bào)名
和我們?cè)诰€交談!