82 days break through 1000star, the project team sorted out eight aspects of open source software must pay attention to

Keywords: Programming Apache github Maven xml

Recently, we have opened source SIA-TASK on GitHub, and have harvested 1000 + star s in 82 days. Since this is the first open source project of SIA team, the related work of open source, the team did not have much experience before, so we have sorted out the various records of this open source project, hoping to provide reference for future open source projects.

Key steps

  1. Development
  2. Agreement
  3. Safety Scanning
  4. File
  5. version number
  6. Open Source
  7. Later stage
  8. iteration

Next we will elaborate step by step.

I. Development

The following points should be noted in the development of open source projects:

First of all, to give your own project a proper name, the naming rules are not repeated here, it needs to be emphasized that the project name can not be the same as the open source project name on GitHub.

Secondly, choose the appropriate programming language.

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

Finally, the choice of open source protocols is discussed. At present, there are six most popular open source protocols: GPL, BSD, MIT, Mozilla, Apache and LGPL.

The differences between different open source protocols are quite big. How to choose them can be consulted. Understanding Open Source Protocol with a Graph(https://blog.csdn.net/cwt19902010/article/details/53736746), if these commonly used 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

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

II. Agreement

After the project is completed, it is necessary 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. Plug-in configuration see License Maven Plugin(https://www.mojohaus.org/license-maven-plugin/. An example of the configuration of the Maven license plug-in in the main pom is as follows. (Here, the open source protocol uses Apache.) 2.0)

    <!--Open source protocol adoption Apache 2.0 Agreement-->
            <name>Apache License, Version 2.0</name>

                 <!-- config for license:aggregate-add-third-party -->
                     <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>

                 <!-- config for license:aggregate-download-licenses -->

                 <!-- config for license:update-file-header -->

                 <!-- config for mvn license:update-project-license -->

After the configuration is completed, the corresponding protocol can be generated to the corresponding file by executing the following commands, which are 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, it is necessary 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 the above commands are executed, several protocol files are generated, including two key files:

LICENSE file: Stores open source protocol information used in current open source projects. </br>
LICENSE-3RD-PARTY file: Protocol used by components. </br>

Look at the protocol used by components in the LICENSE-3RD-PARTY file. Refer to the protocol conflicts mentioned above, see if the protocol used in components conflicts with the open source protocol selected by the current open source project. If there are conflicts, the interface of protocol conflicts needs to be replaced.

Safety Scanning

Security scanning is an indispensable step in the project open source process. The main concerns of security scanning are as follows:

  • Component-level security issues. For example: whether there is remote code execution risk, XXE risk and so on.
  • Code-level security issues. For example, requests for unrestricted methods on RequestMapping, etc.
  • Is the company's sensitive information leaked? For example: database connection information, mailbox information and so on are exposed.

Note: The work of security scanning is performed 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, users can understand the functions of open source projects better and reduce the cost of users. It can be said that open source projects with good README documentation are not necessarily good open source projects, but good open source projects have good README documentation.

The following is a brief introduction to the README documentation specification. Based on the README documents of many large open source projects on GitHub, I think that READEME documents mainly consist of the following parts:

1) Project introduction

The purpose of project introduction is to let others know 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, so that users can better understand the implementation principle of the project.

3) Project Integration

The project integration approach is the project development guide, which can list the deployment of the project or the use of jar packages.

4) Project Use Guidelines

A project usage guide tells users how to use the project. It's better to attach screenshots for each step, which can reduce the cost of communication with users later.

5) Version description

Here you need to tell users which version is more stable.

6) Copyright Description

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

7) Project communication mode

In the project communication mode part, we can leave the contact information of open source authors or organizations, such as micro-mail, micro-blog and mailbox, to facilitate further technical communication between users and open source authors.

V. Version

Open source projects on GitHub require a version number in the following format: the main version number, the minor version number, the revision number, and the incremental rule of the version number is as follows:

  • Major Version Number: When you make incompatible API changes;
  • Second Version Number: When you do downward compatible functionality adds;
  • Revision No. When you make a downward compatibility problem correction.

Advanced version number and version compilation metadata can be added after "main version number, minor version number, revision number" as an extension.

A more vivid explanation is as follows: the standard version number must be in the form of X.Y.Z, where X, Y and Z are non-negative integers and zero-filling is prohibited in front of the number. X is the main version number, Y is the minor version number, and Z is the revision number. Each element must be incremented numerically. For example: 1.9.1 - > 1.10.0 - > 1.11.0.

Note: The Open Source Version Specification is quoted from GitHub Naming Specification: Semantic Version 2.0.0: https://semver.org/lang/zh-CN/

VI. Open Source

After these steps, we can upload the project to GitHub for open source. There are many articles on GitHub's usage on the Internet, which can be referred to here. Participate in the day-to-day process of 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 overlooked in open source projects. In order to make users better use of open source projects, we can do a good job of open source post-maintenance service through interactive forms such as GitHub issue, Wechat Answer Group, Forum, Community Article Sharing and so on.


Iterative development process on GitHub is as follows: project owner sets member rights to project developers, member user fork open source project resources into their own resources, then modify the resources after fork, after modification is completed, make merge request, only project owner has permission to merge. How to synchronize fork projects can be seen in the following articles How to synchronize fork projects: https://blog.csdn.net/t111t/article/details/45894381

Open source projects:

Microservice Task Scheduling Framework: https://github.com/siaorg/sia-task

Microservice Routing Gateway: https://github.com/siaorg/sia-gateway

Author: Zhang Lijun

Posted by Jeroen_nld on Mon, 02 Sep 2019 20:51:44 -0700