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

一、開發(fā)

在開源項目的開發(fā)過程中要注意以下幾點：

• 首先，要給自己的項目取一個合適的名字，取名規(guī)則這里不再贅述，需要強調(diào)的一點是：項目名稱不能與GitHub上已開源過的項目名稱相同。
• 其次，選擇合適的編程語言。
• 再次，編碼過程中要注意代碼的規(guī)范。

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

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

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

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

二、協(xié)議

項目開發(fā)完成之后，需要梳理出項目中使用到的協(xié)議（包含項目引用的組件中用到的協(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é)議到對應(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` 

項目開源時，需要在源文件的頂部添加一個保護許可，修改、檢查、刪除源文件頭部保護許可命令如下：

#### 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í)行完上述命令之后，會生成幾個協(xié)議文件，其中有兩個關(guān)鍵的文件：

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

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

三、安全掃描 

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

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

四、文檔 

README文檔相當(dāng)于開源項目的一個門面，如果README文檔寫得好，能夠讓用戶更了解開源項目的功能，減少用戶的使用成本?？梢哉fREADME文檔寫得好的開源項目不一定是好的開源項目，但是好的開源項目的README文檔寫得一定好。

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

1）項目介紹

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

2）項目架構(gòu)

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

3）項目集成方式 

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

4）項目使用指南

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

5）版本說明

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

6）版權(quán)說明

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

7）項目交流方式

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

五、版本 

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

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

六、開源

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

七、后期

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

八、迭代

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