Recently, we have open source on GitHub micro-service task scheduling framework SIA-TASK, 82 days, harvest 1000 + a star! Since this is the first time the team SIA open source projects, open source-related work before the team did not have much experience, so we've put together this record various items of open source, open source of hope for the future project reference.
key step
- Develop
- protocol
- Security Scan
- File
- version number
- Open source
- Later period
- Iteration
Here we elaborate by-step.
First, the development
During development of open source projects should pay attention to the following points:
First, give your project take a proper name, the name rules will not repeat them here, needs to be emphasized is this: Project name can not be the same as open source on GitHub already have the item name.
Next, choose suitable programming language.
Again, pay attention to the encoding process specification code.
Last but not least is to choose open source license, and the most popular open source license following six: GPL, BSD, MIT, Mozilla, Apache and LGPL.
Differences between different open-source agreement is still getting bigger, specifically how to choose, you can refer to "a map to understand open source license," if these commonly used open-source protocols are not suitable for your project, you can also write your own own open source agreement.
To make it easier to see in FIG open protocol selection, as follows with reference to FIG.
In Apache License Version 2.0 protocol as an example, and Apache protocol commonly used protocol conflict, the conflict is as follows:
Second, the agreement
After the completion of project development, need to sort out the items used in the protocol (the protocol component contains references used in the project), recommended maven license plug-in here. See plugin configuration License Maven Plugin ( https://www.mojohaus.org/license-maven-plugin/),maven license in the main plug-pom configuration example as follows (where the open source protocol uses the 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><<</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>
After configuration, run the following command to generate the corresponding protocol to the corresponding file, the command is as follows:
#### 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`
When the open-source project, you need to add the source file at the top of a protection license, modify, inspect, delete the source files of the head protection license command is as follows:
#### 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
After the completion of the implementation of the above command will generate a file several protocols, including two key documents:
LICENSE文件：存放当前开源项目中用到的开源协议信息。 </br>
LICENSE-3RD-PARTY文件：组件使用到的协议。</br>View components used in LICENSE-3RD-PARTY file protocol, each protocol reference conflict situation described earlier, to see to see if the protocol components used in the current conflict with open source licenses open source projects selected, if there is a conflict, we need to replace interface protocol conflict.
Third, the security scan
Security scanning project is an essential step in the process of open source, security scanning points of interest mainly in the following:
- Component-level security issues. For example: whether the component remote code execution risk, XXE risk.
- Code-level security issues. For example: On request RequestMapping unrestricted method.
- The company sensitive information is compromised. For example: a database connection information, mail information is exposed.
Note: Scan the responsibility of the Ministry of Security and Safety Services colleagues to complete the team, after the completion of the development project, you can contact colleagues on the Security Services team code security scanning work.
Fourth, the document
README document equivalent to a facade open source project, if README document written well, allowing users to better understand the function of open source projects, reduce cost of ownership. It can be said README document written good open source project is not necessarily a good open source project, but the README document good open source projects written some good.
The following outlines the preparation of specifications under README document. Many large-scale open source projects integrated in the README file on GitHub, think READEME document consists of the following components:
1) Projects
Projects are quick to let people understand the project. The main contents include project background, project profiles.
2) architecture project
Implementation of the project focuses on architecture projects, allowing users to achieve a better understanding of the principles of the project.
3) project in an integrated manner
Project Integration Guide way that the project development, deployment can list items, or use a jar.
4) Project Guide
Project Guide also tells the user how to use the project. Best to attach a screenshot of each step using information, which could reduce the cost of communication between late with the user.
5) Imprint
Here you need to tell the user which version is more stable.
6) Copyright
Copyright information can be used for the author's rights, protection of legitimate rights and interests of the version information.
7) project of communication
Project of communication can leave part of the open-source organization or a micro-channel, microblogging, e-mail and other contact information, user-friendly and open source technology of further communication.
Five, version
Open-source project on GitHub need to have a version number, the version in the format: major version minor version number revision number, the version number is incremented rules are as follows:
- The major version number: When you make an incompatible API modifications;
- Minor version number: When you do a functional backward compatible with the new;
- Revision number: When you do a downward compatibility problems fixed.
The version number and the version of the compiler first metadata may be added to the "major version number. Minor version number. Revision number," the latter, as an extension.
More image is explained as follows: The version number must be standard format XYZ, wherein X, Y and Z are non-negative integers, and prohibits the digital front zeros. X is the major version, Y is the minor version number, and Z is the revision number. Each element must be incremented value. For example: 1.9.1 -> 1.10.0 -> 1.11.0.
Note: The open source version of the specification quoted from GitHub naming convention: Semantic version 2.0.0 : https://semver.org/lang/zh-CN/
Sixth, open source
After finishing the above steps work, we can put the items were uploaded to GitHub open source. There are many online using GitHub's article describes, not repeat them here.
Seven, late
Open source is a post-maintenance services open source projects most likely to be ignored, to allow users to make better use of open source projects, we can do a good job sharing and other interactive forms of open source post-service work through GitHub issue, Q & A micro-channel groups, forums, communities article.
Eight, iterative
On GitHub iterative development process as follows: the project owner to the project developer to set member permissions, resource fork member users of open source projects into their own resources, and then modify the resource after the fork, after the modifications are complete, mention merge request, only the project owner only permissions merge.
Open source projects:
Micro-service task scheduling framework: https://github.com/siaorg/sia-task
Micro-service routing gateway: https://github.com/siaorg/sia-gateway
Author: Lijun