82天突破1000star项目团队梳理出软件开源必须注意的8个方面

jiezi

5 年前

近期，我们在 GitHub 上开源了微服务任务调度框架 SIA-TASK，82 天，收获了 1000+ 个 star！由于这是 SIA 团队第一次开源项目，开源的相关工作，团队之前并没有太多的经验，因此我们特别整理了本次开源的各种记录事项，希望给今后开源的项目做参考。

开发
协议
安全扫描
文档
版本号
开源
后期
迭代

下面我们逐个步骤进行阐述。

在开源项目的开发过程中要注意以下几点：

首先，要给自己的项目取一个合适的名字，取名规则这里不再赘述，需要强调的一点是：项目名称不能与 GitHub 上已开源过的项目名称相同。

其次，选择合适的编程语言。

再次，编码过程中要注意代码的规范。

最后要说的就是开源协议的选择了，目前最流行的开源协议有以下六种：GPL、BSD、MIT、Mozilla、Apache 和 LGPL。

不同的开源协议之间的差别还是挺大的，具体如何选择，可以参考一张图看懂开源协议（https://blog.csdn.net/cwt1990…），如果这些常用的开源协议都不适合你的项目，你也可以自己写一个自己的开源协议。

为了更方便查看开源协议选择图，参考图如下

以 Apache License Version 2.0 协议为例, 比较常用协议与 Apache 协议冲突情况，冲突图如下：

项目开发完成之后，需要梳理出项目中使用到的协议（包含项目引用的组件中用到的协议），此处推荐使用 maven 许可证插件。插件配置参见 License Maven Plugin（https://www.mojohaus.org/lice…），maven 许可证插件在主 pom 中配置示例如下（此处开源协议采用 Apache 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>&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>

配置完成之后，执行如下命令即可生成相应的协议到对应的文件，命令如下：

#### 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：https://semver.org/lang/zh-CN/

做完上述几步的工作之后，我们就可以把项目上传到 GitHub 上进行开源了。GitHub 的使用网上有很多文章介绍，这里不再赘述，可以参考
在 GitHub 上参与开源项目日常流程：https://blog.csdn.net/five3/a…

开源后期维护服务是开源项目时最容易被忽视的，为了让用户更好地使用开源项目，我们可以通过 GitHub issue、微信答疑群、论坛、社区文章分享等互动形式做好开源后期服务工作。

GitHub 上迭代开发流程如下：项目 owner 给项目开发者设置 member 权限，member 用户 fork 开源项目的资源成自己的资源，然后修改 fork 之后的资源，修改完成之后，提 merge 请求，只有项目 owner 才有权限 merge。如何同步 fork 项目可参见如下文章如何同步 fork 项目：https://blog.csdn.net/t111t/a…

开源项目：

微服务任务调度框架：https://github.com/siaorg/sia…

微服务路由网关：https://github.com/siaorg/sia…

作者: 张丽君

82天突破1000star项目团队梳理出软件开源必须注意的8个方面

关键步骤

一、开发

二、协议

三、安全扫描

四、文档

五、版本

六、开源

七、后期

八、迭代