Shulou(Shulou.com)06/02 Report--

Recently, we opened up the micro-service task scheduling framework SIA-TASK,82 days on GitHub, and gained 1000 + star! As this is the SIA team's first open source project, open source related work, the team did not have much experience before, so we specially sorted out the various records of this open source project, hoping to provide reference for future open source projects.

Key steps development protocol security scan document version number open source late iteration

Let's elaborate on it step by step.

I. Development

Pay attention to the following points during the development of an open source project:

First of all, to give your project an appropriate name, the naming rules are not repeated here, and it is important to emphasize that the project name cannot be the same as the open source project name on GitHub.

Second, choose the appropriate programming language.

Thirdly, we should pay attention to the code specification in the coding process.

The last thing to talk about is the choice of open source protocols. At present, there are six most popular open source protocols: GPL, BSD, MIT, Mozilla, Apache and LGPL.

There are great differences between different open source protocols. For more information on how to choose, please refer to a picture to understand the open source protocols (https://blog.csdn.net/cwt19902010/article/details/53736746). If these common open source protocols are not suitable for your project, you can also write your own open source protocol.

To make it easier to view the open source protocol selection diagram, refer to the following figure

Taking Apache License Version 2.0 protocol as an example, the conflicts between common protocols and Apache protocols are compared. The conflict chart is as follows:

II. Agreement

After the project development is complete, you need to sort out the protocols used in the project (including those used in the components referenced by the project), and the maven license plug-in is recommended here. For the plug-in configuration, see License Maven Plugin (https://www.mojohaus.org/license-maven-plugin/). The maven license plug-in configuration example in the main pom is as follows (here the open source protocol uses Apache 2.0)

Apache License Version 2.0 http://www.apache.org/licenses/LICENSE-2.0.html repo org.codehaus.mojo license-maven-plugin 1.13 ${main.basedir} LICENSE-3RD-PARTY / org/codehaus/mojo/license/third-party-file-groupByLicense.ftl true ${main.basedir} / LICENSE-3RD-PARTY.properties ${main.basedir} / LICENSE-3RD-PARTY.properties 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 BSD | The BSD 3-Clause License | Modified BSD License | New BSD License | New BSD license | Two-clause BSD-style license | BSD New | The New BSD License | BSD 3-Clause | BSD 3-clause MIT | MIT License | The MIT License 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 CDDL | CDDL+GPL | CDDL+GPL License | 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 EPL | Eclipse Public License-Version 1.0 GPL | GPL2 w / CPE | GPLv2+CE | GNU General Public Library MPL | MPL 1.1 Public Domain Common Public License | Common Public License Version 1.0 CC0 | CC0 1.0 Universal | Public Domain Per Creative Commons CC0 Unknown License | Unknown license true ${main.basedir} / lic/licenses.xml ${main.basedir} / lic/licenses/ apache_v2 2019 Sia task src/main/java src/test/java * * / * .java * * / .xml * * / * .sh * * / * .py * * / * .properties * * / * .sql * * / * .html * / * .less * / * .css * * / * .js * * / * .json true true false true = = ${main.basedir} / LICENSE Org.jasig.maven maven-notice-plugin 1.0.6.1 false https://source.jasig.org/licenses/NOTICE.template https://source.jasig.org/licenses/license-mappings.xml

After the configuration is completed, execute the following command to generate the corresponding protocol to the corresponding file, 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 project is open source, you need to add a protection license at the top of the source file. Modify, check, and delete the source file header protection license command 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 executing the above command, several protocol files are generated, including two key files:

LICENSE file: stores open source protocol information used in current open source projects. LICENSE-3RD-PARTY file: the protocol used by the component.

Check the protocol used by the component in the LICENSE-3RD-PARTY file, refer to the protocol conflicts described earlier, and see if the protocol used in the component conflicts with the open source protocol selected by the current open source project. If there is a conflict, you need to replace the interface with the protocol conflict.

III. Security scanning

Security scanning is an essential step in the open source process of the project. Security scanning focuses on the following points:

Component-level security issues. For example: whether the component has remote code execution risk, XXE risk and so on. Code-level security issues. For example: request unrestricted methods on RequestMapping and so on. Whether the company's sensitive information is leaked. For example, database connection information, mailbox information and so on are exposed.

Note: the security scanning work is carried out by the colleagues of the security service team of the Ministry of Security. After the project development is completed, you can contact the colleagues of the security service team for code security scanning.

IV. Documentation

README documents are equivalent to a facade of open source projects. If README documents are well written, they can make users better understand the functions of open source projects and reduce user costs. It can be said that a well-documented README open source project is not necessarily a good open source project, but a good open source project README documentation must be well written.

The following is a brief introduction to the writing specifications of README documents. Synthesizing the README documents of many large open source projects on GitHub, I think READEME documents are mainly composed of the following parts:

1) Project introduction

The purpose of the project introduction is to let others understand the project quickly. The main contents include project background and project introduction.

2) Project architecture

The project architecture mainly introduces the implementation of the project, which allows users to better understand the implementation principle of the project.

3) Project integration mode

The project integration approach is the project development guide, which can list how the project is deployed, or how the jar package is used.

4) Project usage guide

The project usage guide tells the user how to use the project. It is best to attach screenshots of each step, so as to reduce the cost of communication with users at a later stage.

5) release Notes

Here you need to tell the user which version is more stable.

6) copyright description

Copyright information can be used to protect the author's rights and protect the legitimate rights and interests of the author's version information.

7) Project communication mode

The project communication part can leave contact information such as Wechat, Weibo, email of the open source author or organization, so as to facilitate further technical communication between the user and the open source author.

V. version

Open source projects on GitHub need a version number, the version format is: major version number. The second edition number. Revision number, version number increment rules are as follows:

Major version number: when you have made incompatible API changes; minor version number: when you have made downward compatible functionality additions; revision number: when you have made downward compatible problem fixes.

The previous version number and version compilation metadata can be added to the major version number. minor version number. after the revision number, as an extension.

A more vivid explanation is as follows: the standard version number must be in X.Y.Z format, where X, Y and Z are non-negative integers and zero padding before the number is prohibited. X is the major version number, Y is the minor version number, and Z is the revision number. Each element must be incremented by a numerical value. For example: 1.9.1-> 1.10.0-> 1.11.0.

Note: the open source version specification is quoted from the GitHub naming convention: semantic version 2.0.0: https://semver.org/lang/zh-CN/

VI. Open Source

After completing the above steps, we can upload the project to GitHub for open source. There are many articles about the use of GitHub on the Internet. I will not repeat them here. You can refer to the daily process of participating in open source projects on GitHub: https://blog.csdn.net/five3/article/details/9307041

VII. Later period

Open source post-maintenance service is the most easily ignored when open source projects. In order to let users make better use of open source projects, we can do a good job in open source post-service work through interactive forms such as GitHub issue, Wechat Q & A groups, forums, community articles sharing and so on.

VIII. Iteration

The iterative development process on GitHub is as follows: project owner sets member permissions to project developers, member users fork open source project resources into their own resources, and then modify the resources after fork. After the modification is completed, submit a merge request. Only the project owner has permission merge. How to synchronize fork projects can be found in the following article: how to synchronize fork projects: https://blog.csdn.net/t111t/article/details/45894381

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: Zhang Lijun

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.