82天突破1000star,專案團隊梳理出軟體開源必須注意的8個方面
近期,我們在GitHub上開源了微服務任務排程框架SIA-TASK,82天,收穫了1000+個star!由於這是SIA團隊第一次開源專案,開源的相關工作,團隊之前並沒有太多的經驗,因此我們特別整理了本次開源的各種記錄事項,希望給今後開源的專案做參考。
關鍵步驟
- 開發
- 協議
- 安全掃描
- 檔案
- 版本號
- 開源
- 後期
- 迭代
下面我們逐個步驟進行闡述。
一、開發
在開源專案的開發過程中要注意以下幾點:
首先,要給自己的專案取一個合適的名字,取名規則這裡不再贅述,需要強調的一點是:專案名稱不能與GitHub上已開源過的專案名稱相同。
其次,選擇合適的程式語言。
再次,編碼過程中要注意程式碼的規範。
最後要說的就是開源協議的選擇了,目前最流行的開源協議有以下六種:GPL、BSD、MIT、Mozilla、Apache和LGPL。
不同的開源協議之間的差別還是挺大的,具體如何選擇,可以參考一張圖看懂開源協議(blog.csdn.net/cwt19902010…
為了更方便檢視開源協議選擇圖,參考圖如下
以Apache License Version 2.0協議為例,比較常用協議與Apache協議衝突情況,衝突圖如下:
二、協議
專案開發完成之後,需要梳理出專案中使用到的協議(包含專案引用的元件中用到的協議),此處推薦使用maven許可證外掛。外掛配置參見License Maven Plugin(www.mojohaus.org/license-mav… 2.0)
<!--開源協議採用Apache 2.0協議-->
<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><<</processStartTag>
<processEndTag>>></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>
複製程式碼
配置完成之後,執行如下命令即可生成相應的協議到對應的檔案,命令如下:
#### 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`
複製程式碼
專案開源時,需要在原始檔的頂部新增一個保護許可,修改、檢查、刪除原始檔頭部保護許可命令如下:
#### 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
複製程式碼
執行完上述命令之後,會生成幾個協議檔案,其中有兩個關鍵的檔案:
LICENSE檔案:存放當前開源專案中用到的開源協議資訊。 </br>
LICENSE-3RD-PARTY檔案:元件使用到的協議。</br>
複製程式碼
在LICENSE-3RD-PARTY檔案中檢視元件使用的協議,參考前面介紹的各協議衝突情況,檢視看元件中用到的協議是否與當前開源專案選擇的開源協議有衝突,如果有衝突,需要替換掉協議衝突的介面。
三、安全掃描
安全掃描是專案開源流程中必不可少的一步,安全掃描關注的點主要有以下幾個:
- 元件層面安全問題。比如:元件是否存在遠端程式碼執行風險、XXE風險等。
- 程式碼層面安全問題。比如:RequestMapping上請求未限制方法等。
- 公司敏感資訊是否外洩。比如:資料庫連線資訊、郵箱資訊等被暴露。
備註:安全掃描工作由安全部·安全服務團隊的同事負責完成,專案開發完成之後,可聯絡安全服務團隊的同事進行程式碼安全掃描工作。
四、檔案
README檔案相當於開源專案的一個門面,如果README檔案寫得好,能夠讓使用者更瞭解開源專案的功能,減少使用者的使用成本。可以說README檔案寫得好的開源專案不一定是好的開源專案,但是好的開源專案的README檔案寫得一定好。
下面簡單介紹下README檔案的編寫規範。綜合GitHub上很多大型開源專案的README檔案,個人認為READEME檔案主要由以下幾部分組成:
1)專案介紹
專案介紹是為了讓別人快速瞭解專案。主要內容包括專案背景、專案簡介。
2)專案架構
專案架構主要介紹專案的實現方式,可以讓使用者更瞭解專案的實現原理。
3)專案整合方式
專案整合方式即專案開發指南,可以列出專案的部署方式,或者是jar包的使用方式。
4)專案使用指南
專案使用指南也就是告訴使用者怎麼使用專案。最好是附上每一步的使用截圖資訊,這樣能減少後期跟使用者之間的溝通成本。
5)版本說明
此處需要告訴使用者使用哪個版本更穩定。
6)版權說明
版權資訊可以用於作者的維權,保護作者版本資訊的合法權益。
7)專案交流方式
專案交流方式部分可以留下開源作者或者是組織的微信、微博、郵箱等聯絡方式,方便使用者與開源作者進一步技術溝通。
五、版本
GitHub上開源的專案需要有個版本號,版本格式為:主版本號.次版本號.修訂號,版本號遞增規則如下:
- 主版本號:當你做了不相容的 API 修改;
- 次版本號:當你做了向下相容的功能性新增;
- 修訂號:當你做了向下相容的問題修正。
先行版本號及版本編譯元資料可以加到“主版本號.次版本號.修訂號”的後面,作為延伸。
更形象的解釋如下:標準的版本號必須採用 X.Y.Z 的格式,其中 X、Y 和 Z 為非負的整數,且禁止在數字前方補零。X 是主版本號、Y 是次版本號、而 Z 為修訂號。每個元素必須以數值來遞增。例如:1.9.1 -> 1.10.0 -> 1.11.0。
備註:開源版本規範引自GitHub命名規範:語義化版本2.0.0:semver.org/lang/zh-CN/
六、開源
做完上述幾步的工作之後,我們就可以把專案上傳到GitHub上進行開源了。GitHub的使用網上有很多文章介紹,這裡不再贅述,可以參考 在GitHub上參與開源專案日常流程:blog.csdn.net/five3/artic…
七、後期
開源後期維護服務是開源專案時最容易被忽視的,為了讓使用者更好地使用開源專案,我們可以通過GitHub issue、微信答疑群、論壇、社群文章分享等互動形式做好開源後期服務工作。
八、迭代
GitHub上迭代開發流程如下:專案owner給專案開發者設定member許可權,member使用者fork開源專案的資源成自己的資源,然後修改fork之後的資源,修改完成之後,提merge請求,只有專案owner才有許可權merge。如何同步fork專案可參見如下文章如何同步fork專案:blog.csdn.net/t111t/artic…
開源專案:
微服務任務排程框架 :github.com/siaorg/sia-…
微服務路由閘道器 :github.com/siaorg/sia-…
作者: 張麗君
來源:宜信技術學院