溫馨提示×

您好,登錄后才能下訂單哦!

密碼登錄×
登錄注冊(cè)×
其他方式登錄
點(diǎn)擊 登錄注冊(cè) 即表示同意《億速云用戶服務(wù)條款》

82天突破1000star,項(xiàng)目團(tuán)隊(duì)梳理出軟件開源必須注意的8個(gè)方面

發(fā)布時(shí)間:2020-08-10 18:27:07 來(lái)源:ITPUB博客 閱讀:195 作者:宜信技術(shù)學(xué)院 欄目:軟件技術(shù)

近期,我們?cè)贕itHub上開源了微服務(wù)任務(wù)調(diào)度框架SIA-TASK,82天,收獲了1000+個(gè)star!由于這是SIA團(tuán)隊(duì)第一次開源項(xiàng)目,開源的相關(guān)工作,團(tuán)隊(duì)之前并沒有太多的經(jīng)驗(yàn),因此我們特別整理了本次開源的各種記錄事項(xiàng),希望給今后開源的項(xiàng)目做參考。

關(guān)鍵步驟

  1. 開發(fā)
  2. 協(xié)議
  3. 安全掃描
  4. 文檔
  5. 版本號(hào)
  6. 開源
  7. 后期
  8. 迭代

下面我們逐個(gè)步驟進(jìn)行闡述。

一、開發(fā)

在開源項(xiàng)目的開發(fā)過(guò)程中要注意以下幾點(diǎn):

首先,要給自己的項(xiàng)目取一個(gè)合適的名字,取名規(guī)則這里不再贅述,需要強(qiáng)調(diào)的一點(diǎn)是:項(xiàng)目名稱不能與GitHub上已開源過(guò)的項(xiàng)目名稱相同。

其次,選擇合適的編程語(yǔ)言。

再次,編碼過(guò)程中要注意代碼的規(guī)范。

最后要說(shuō)的就是開源協(xié)議的選擇了,目前最流行的開源協(xié)議有以下六種:GPL、BSD、MIT、Mozilla、Apache和LGPL。

不同的開源協(xié)議之間的差別還是挺大的,具體如何選擇,可以參考 一張圖看懂開源協(xié)議(https://blog.csdn.net/cwt19902010/article/details/53736746),如果這些常用的開源協(xié)議都不適合你的項(xiàng)目,你也可以自己寫一個(gè)自己的開源協(xié)議。

為了更方便查看開源協(xié)議選擇圖,參考圖如下

82天突破1000star,項(xiàng)目團(tuán)隊(duì)梳理出軟件開源必須注意的8個(gè)方面

以Apache License Version 2.0協(xié)議為例,比較常用協(xié)議與Apache協(xié)議沖突情況,沖突圖如下:

82天突破1000star,項(xiàng)目團(tuán)隊(duì)梳理出軟件開源必須注意的8個(gè)方面

二、協(xié)議

項(xiàng)目開發(fā)完成之后,需要梳理出項(xiàng)目中使用到的協(xié)議(包含項(xiàng)目引用的組件中用到的協(xié)議),此處推薦使用maven許可證插件。插件配置參見 License Maven Plugin(https://www.mojohaus.org/license-maven-plugin/),maven許可證插件在主pom中配置示例如下(此處開源協(xié)議采用Apache 2.0)

    <!--開源協(xié)議采用Apache 2.0協(xié)議-->
    <licenses>
        <license>
            <name>Apache License, Version 2.0</name>
            <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
            <distribution>repo</distribution>
        </license>
    </licenses>
    <plugins>
         <plugin>
             <groupId>org.codehaus.mojo</groupId>
             <artifactId>license-maven-plugin</artifactId>
             <version>1.13</version>
             <configuration>
                 <!-- config for license:aggregate-add-third-party -->
                 <outputDirectory>${main.basedir}</outputDirectory>
                 <thirdPartyFilename>LICENSE-3RD-PARTY</thirdPartyFilename>
                 <fileTemplate>/org/codehaus/mojo/license/third-party-file-groupByLicense.ftl</fileTemplate>
                 <useMissingFile>true</useMissingFile>
                 <missingFile>${main.basedir}/LICENSE-3RD-PARTY.properties</missingFile>
                 <aggregateMissingLicensesFile>${main.basedir}/LICENSE-3RD-PARTY.properties</aggregateMissingLicensesFile>
                 <licenseMerges>
                     <licenseMerge>Apache 2.0|ASL, version 2|http://www.apache.org/licenses/LICENSE-2.0.txt|http://asm.ow2.org/license.html|The Apache License, Version 2.0|Apache License|Apache License Version 2|Apache License Version 2.0|Apache Software License - Version 2.0|Apache 2.0 License|Apache License 2.0|ASL|Apache 2|Apache-2.0|the Apache License, ASL Version 2.0|The Apache Software License, Version 2.0|Apache License, Version 2.0|Apache Public License 2.0</licenseMerge>
                     <licenseMerge>BSD|The BSD 3-Clause License|The BSD License|Modified BSD License|New BSD License|New BSD license|Two-clause BSD-style license|BSD licence|BSD New|The New BSD License|BSD 3-Clause|BSD 3-clause</licenseMerge>
                     <licenseMerge>MIT|MIT License|The MIT License</licenseMerge>
                     <licenseMerge>LGPL|LGPL, version 2.1|GNU Library or Lesser General Public License (LGPL) V2.1|GNU Lesser General Public License (LGPL), Version 2.1|GNU Lesser General Public License, Version 2.1|LGPL 2.1</licenseMerge>
                     <licenseMerge>CDDL|CDDL+GPL|CDDL+GPL License|CDDL + GPLv2 with classpath exception|CDDL License|CDDL 1.0|CDDL 1.1|COMMON DEVELOPMENT AND DISTRIBUTION LICENSE (CDDL) Version 1.0|Common Development and Distribution License (CDDL) v1.0</licenseMerge>
                     <licenseMerge>EPL|Eclipse Public License - Version 1.0</licenseMerge>
                     <licenseMerge>GPL|GPL2 w/ CPE|GPLv2+CE|GNU General Public Library</licenseMerge>
                     <licenseMerge>MPL|MPL 1.1</licenseMerge>
                     <licenseMerge>Public Domain</licenseMerge>
                     <licenseMerge>Common Public License|Common Public License Version 1.0</licenseMerge>
                     <licenseMerge>CC0|CC0 1.0 Universal|Public Domain, per Creative Commons CC0</licenseMerge>
                     <licenseMerge>Unknown License|Unknown license</licenseMerge>
                 </licenseMerges>
                 <!-- config for license:aggregate-download-licenses -->
                 <aggregateDownloadLicenses.executeOnlyOnRootModule>true</aggregateDownloadLicenses.executeOnlyOnRootModule>
                 <!--<licensesConfigFile>${main.basedir}/lic/config/licenses.xml</licensesConfigFile>-->
                 <licensesOutputFile>${main.basedir}/lic/licenses.xml</licensesOutputFile>
                 <licensesOutputDirectory>${main.basedir}/lic/licenses/</licensesOutputDirectory>
                 <!-- config for license:update-file-header -->
                 <licenseName>apache_v2</licenseName>
                 <inceptionYear>2019</inceptionYear>
                 <organizationName>sia</organizationName>
                 <projectName>task</projectName>
                 <roots>
                     <root>src/main/java</root>
                     <root>src/test/java</root>                   
                 </roots>
                 <includes>
                     <include>**/*.java</include>
                     <include>**/*.xml</include>
                     <include>**/*.sh</include>
                     <include>**/*.py</include>
                     <include>**/*.properties</include>
                     <include>**/*.sql</include>
                     <include>**/*.html</include>
                     <include>**/*.less</include>
                     <include>**/*.css</include>
                     <include>**/*.js</include>
                     <include>**/*.json</include>
                 </includes>
                 <canUpdateCopyright>true</canUpdateCopyright>
                 <canUpdateDescription>true</canUpdateDescription>
                 <addJavaLicenseAfterPackage>false</addJavaLicenseAfterPackage>
                 <emptyLineAfterHeader>true</emptyLineAfterHeader>
                 <processStartTag>&lt;&lt;</processStartTag>
                 <processEndTag>&gt;&gt;</processEndTag>
                 <sectionDelimiter>==</sectionDelimiter>
                 <!-- config for mvn license:update-project-license -->
                 <licenseFile>${main.basedir}/LICENSE</licenseFile>
             </configuration>
         </plugin>
         <plugin>
             <groupId>org.jasig.maven</groupId>
             <artifactId>maven-notice-plugin</artifactId>
             <version>1.0.6.1</version>
             <configuration>
                 <generateChildNotices>false</generateChildNotices>
                 <noticeTemplate>https://source.jasig.org/licenses/NOTICE.template</noticeTemplate>
                 <licenseMapping>
                     <param>https://source.jasig.org/licenses/license-mappings.xml</param>
                 </licenseMapping>
             </configuration>
         </plugin>
     </plugins>

配置完成之后,執(zhí)行如下命令即可生成相應(yīng)的協(xié)議到對(duì)應(yīng)的文件,命令如下:

#### Updates (or creates) the main project license file according to the license defined in the licenseName parameter.
`mvn license:update-project-license`
#### Generates a file containing a list of all dependencies and their licenses for a multi-module build.
`mvn license:aggregate-add-third-party`
#### Downloads the license files associated with each dependency for a multi-modules build.
`mvn license:aggregate-download-licenses`
#### Generate NOTICE?
`mvn notice:generate`

項(xiàng)目開源時(shí),需要在源文件的頂部添加一個(gè)保護(hù)許可,修改、檢查、刪除源文件頭部保護(hù)許可命令如下:

#### how to generate/update source code header?
## Updates the license header of the current project source files.
mvn license:update-file-header
## Checks the license header of the current project source files.
mvn license:check-file-header
## Remove any license header of the current project source files.
mvn license:remove-file-header

執(zhí)行完上述命令之后,會(huì)生成幾個(gè)協(xié)議文件,其中有兩個(gè)關(guān)鍵的文件:

LICENSE文件:存放當(dāng)前開源項(xiàng)目中用到的開源協(xié)議信息。 </br>
LICENSE-3RD-PARTY文件:組件使用到的協(xié)議。</br>

在LICENSE-3RD-PARTY文件中查看組件使用的協(xié)議,參考前面介紹的各協(xié)議沖突情況,查看看組件中用到的協(xié)議是否與當(dāng)前開源項(xiàng)目選擇的開源協(xié)議有沖突,如果有沖突,需要替換掉協(xié)議沖突的接口。

三、安全掃描

安全掃描是項(xiàng)目開源流程中必不可少的一步,安全掃描關(guān)注的點(diǎn)主要有以下幾個(gè):

  • 組件層面安全問題。比如:組件是否存在遠(yuǎn)程代碼執(zhí)行風(fēng)險(xiǎn)、XXE風(fēng)險(xiǎn)等。
  • 代碼層面安全問題。比如:RequestMapping上請(qǐng)求未限制方法等。
  • 公司敏感信息是否外泄。比如:數(shù)據(jù)庫(kù)連接信息、郵箱信息等被暴露。

備注:安全掃描工作由安全部·安全服務(wù)團(tuán)隊(duì)的同事負(fù)責(zé)完成,項(xiàng)目開發(fā)完成之后,可聯(lián)系安全服務(wù)團(tuán)隊(duì)的同事進(jìn)行代碼安全掃描工作。

四、文檔

README文檔相當(dāng)于開源項(xiàng)目的一個(gè)門面,如果README文檔寫得好,能夠讓用戶更了解開源項(xiàng)目的功能,減少用戶的使用成本。可以說(shuō)README文檔寫得好的開源項(xiàng)目不一定是好的開源項(xiàng)目,但是好的開源項(xiàng)目的README文檔寫得一定好。

下面簡(jiǎn)單介紹下README文檔的編寫規(guī)范。綜合GitHub上很多大型開源項(xiàng)目的README文檔,個(gè)人認(rèn)為READEME文檔主要由以下幾部分組成:

1)項(xiàng)目介紹

項(xiàng)目介紹是為了讓別人快速了解項(xiàng)目。主要內(nèi)容包括項(xiàng)目背景、項(xiàng)目簡(jiǎn)介。

2)項(xiàng)目架構(gòu)

項(xiàng)目架構(gòu)主要介紹項(xiàng)目的實(shí)現(xiàn)方式,可以讓用戶更了解項(xiàng)目的實(shí)現(xiàn)原理。  

3)項(xiàng)目集成方式  

項(xiàng)目集成方式即項(xiàng)目開發(fā)指南,可以列出項(xiàng)目的部署方式,或者是jar包的使用方式。

4)項(xiàng)目使用指南

項(xiàng)目使用指南也就是告訴用戶怎么使用項(xiàng)目。最好是附上每一步的使用截圖信息,這樣能減少后期跟用戶之間的溝通成本。

5)版本說(shuō)明

此處需要告訴用戶使用哪個(gè)版本更穩(wěn)定。

6)版權(quán)說(shuō)明

版權(quán)信息可以用于作者的維權(quán),保護(hù)作者版本信息的合法權(quán)益。

7)項(xiàng)目交流方式

項(xiàng)目交流方式部分可以留下開源作者或者是組織的微信、微博、郵箱等聯(lián)系方式,方便用戶與開源作者進(jìn)一步技術(shù)溝通。

五、版本

GitHub上開源的項(xiàng)目需要有個(gè)版本號(hào),版本格式為:主版本號(hào).次版本號(hào).修訂號(hào),版本號(hào)遞增規(guī)則如下:

  • 主版本號(hào):當(dāng)你做了不兼容的 API 修改;
  • 次版本號(hào):當(dāng)你做了向下兼容的功能性新增;
  • 修訂號(hào):當(dāng)你做了向下兼容的問題修正。

先行版本號(hào)及版本編譯元數(shù)據(jù)可以加到“主版本號(hào).次版本號(hào).修訂號(hào)”的后面,作為延伸。

更形象的解釋如下:標(biāo)準(zhǔn)的版本號(hào)必須采用 X.Y.Z 的格式,其中 X、Y 和 Z 為非負(fù)的整數(shù),且禁止在數(shù)字前方補(bǔ)零。X 是主版本號(hào)、Y 是次版本號(hào)、而 Z 為修訂號(hào)。每個(gè)元素必須以數(shù)值來(lái)遞增。例如:1.9.1 -> 1.10.0 -> 1.11.0。

備注:開源版本規(guī)范引自 GitHub命名規(guī)范:語(yǔ)義化版本2.0.0:https://semver.org/lang/zh-CN/

六、開源

做完上述幾步的工作之后,我們就可以把項(xiàng)目上傳到GitHub上進(jìn)行開源了。GitHub的使用網(wǎng)上有很多文章介紹,這里不再贅述,可以參考   在GitHub上參與開源項(xiàng)目日常流程:https://blog.csdn.net/five3/article/details/9307041

七、后期

開源后期維護(hù)服務(wù)是開源項(xiàng)目時(shí)最容易被忽視的,為了讓用戶更好地使用開源項(xiàng)目,我們可以通過(guò)GitHub issue、微信答疑群、論壇、社區(qū)文章分享等互動(dòng)形式做好開源后期服務(wù)工作。

八、迭代

GitHub上迭代開發(fā)流程如下:項(xiàng)目owner給項(xiàng)目開發(fā)者設(shè)置member權(quán)限,member用戶fork開源項(xiàng)目的資源成自己的資源,然后修改fork之后的資源,修改完成之后,提merge請(qǐng)求,只有項(xiàng)目owner才有權(quán)限merge。如何同步fork項(xiàng)目可參見如下文章 如何同步fork項(xiàng)目:https://blog.csdn.net/t111t/article/details/45894381

開源項(xiàng)目:

微服務(wù)任務(wù)調(diào)度框架 :https://github.com/siaorg/sia-task

微服務(wù)路由網(wǎng)關(guān) :https://github.com/siaorg/sia-gateway

作者: 張麗君

向AI問一下細(xì)節(jié)

免責(zé)聲明:本站發(fā)布的內(nèi)容(圖片、視頻和文字)以原創(chuàng)、轉(zhuǎn)載和分享為主,文章觀點(diǎn)不代表本網(wǎng)站立場(chǎng),如果涉及侵權(quán)請(qǐng)聯(lián)系站長(zhǎng)郵箱:is@yisu.com進(jìn)行舉報(bào),并提供相關(guān)證據(jù),一經(jīng)查實(shí),將立刻刪除涉嫌侵權(quán)內(nèi)容。

AI