Skip to content

Latest commit

 

History

History
145 lines (92 loc) · 7.35 KB

CONTRIBUTING.adoc

File metadata and controls

145 lines (92 loc) · 7.35 KB
Raw

HiveMQ Community Edition Contributing Guidelines

Introduction

Anyone is welcome to participate and contribute to the HiveMQ open source community. We encourage people to use the Github issue tracker and create pull requests. The scope of the HiveMQ CE is to provide

  1. a high-quality implementation of the MQTT broker specification, and

  2. the extension framework enabling the integration of HiveMQ CE into other applications.

Therefore, we ask that contributions are focused on improving the current implementation and project scope.

We will not accept contributions that would add features that expand the scope of the project. It is HiveMQ’s intention to offer commercial products that will add features suited for enterprise deployments of HiveMQ, such as clustering, monitoring tools, enterprise security, technical support, and more. We also expect that other companies and open source projects will create extensions of HiveMQ CE to suit their specific customer requirements. If you would like to suggest a new feature, please contact the project team (support@hivemq.com) to discuss if it fits within the project scope. If you wish to contribute, we will preferibly accept Bug Fixes, Typos, Documentation, JavaDoc and Logging.

Licensing

HiveMQ CE is released under the Apache 2.0 license to allow you the use of the software as you please. By contributing your code, you agree to license your contribution under the terms of the Apache License, Version 2.0.

Please fill out our Contributor License Agreement (CLA), otherwise we cannot accept your contribution.

All files must contain the license header from the header file.

Contributor License Agreement

If you wish to contribute to the HiveMQ CE, please download, fill out and sign the Contributor License Agreement. Send the signed agreement to (contributing@hivemq.com) with the subject CLA for Project: HiveMQ Community Edition. Please read this document carefully before signing it and keep a copy for your own records. Once we’ve received your signed CLA, you will be added to the list of contributors and our HiveMQ Development Team will review your contributions.

In case the rights to all intellectual property created by you are maintained by your employer, including your work on HiveMQ CE, you must ensure you have retained all rights to grant the license, or that your employer has agreed to a separate Corporate CLA.

Contribution Guidelines

Issues

Bug Fixes and Minor Features

Please always open an issue in the issue tracker before sending a pull request and wait until someone from the HiveMQ Development Team approves it, before you start working on it. This prevents you from working on issues that we will ultimately not accept. When you start working on an approved issue, please make it known in the comments that you are going to work on it, so a simulteaneous contribution by someone else can be avoided.

After you committed, your contribution will be reviewed by the HiveMQ Development Team. We reserve the right to release only reviewed and approved implementations.

Security Issues

Please do not report any security issue to the public issue tracker. Please send security issues to security@hivemq.com.

Questions

Please refer all your questions about the HiveMQ CE to the HiveMQ Community Forum.

Issues consisting of questions or suggestions will be closed immediately.

Checking out the Project

We recommend that you use the IntelliJ IDE for all development on HiveMQ CE. It will automate your process as much as possible. Java version 11 is required to build and run HiveMQ CE (we recommend OpenJDK 11). You can check your installed Java version by entering java -version on the command line.

First you need to fork the HiveMQ Community Edition repository.

Then you can clone the repository:

git clone https://github.com/<your user name>/hivemq-community-edition.git

Open the HiveMQ CE project folder in IntelliJ. Choose to sync the gradle project, if so prompted by the IDE. After setting the gradle and project SDK (Java 11), you are good to go.

Checking out the HiveMQ Extension SDK

HiveMQ CE uses the HiveMQ Extension SDK which resides in its own repository. By default, you can not use the latest changes of or modify the Extension SDK. Please checkout the hivemq-extension-sdk repository next to the hivemq-community-edition repository. Gradle and IntelliJ will then automatically wire the two projects.

If you only want to use the Extension SDK, execute the following command from the hivemq-community-edition project directory:

git clone https://github.com/hivemq/hivemq-extension-sdk.git ../hivemq-extension-sdk

If you also want to make changes to the Extension SDK, please fork the hivemq-extension-sdk repository and clone your fork:

git clone https://github.com/<your user name>/hivemq-extension-sdk.git ../hivemq-extension-sdk

Branching Model

A modified version of git-flow is used for the structuring of the HiveMQ CE repository.

All branches must start with an issue type tag, usually bugfix or improvement, followed by a slash / and a speaking name describing the code change e.g. bugfix/locking-for-concurrent-access-in-some-class or improvement/better-javadoc-in-some-interface. The pull requests must be opened against the master branch.

Code Style Guidelines

Only code following good Java practices, like using the appropriate keywords and visibility, will be accepted.

HiveMQ CE uses nullability annotations, these should be used to annotate the declared types of variables and fields, whose initialization status can be in question.

Nullability example
class SomeClass {

    // this must never be null, the accessor can depend on it
    private @NotNull SomeType myField;

    // this may be null, the accessor must check
    private @Nullable SomeType anotherField;

}

The following annotations are provided for this purpose:

@Nullable
com.hivemq.extension.sdk.api.annotations.NotNull
com.hivemq.extension.sdk.api.annotations.Nullable

Commit Guidelines

You can set up IntelliJ to recognise these annotations under Preferences > Inspections > @NotNull/@Nullable problems > Configure annotations.

Please watch out for this inspection and check the Reformat code, Optimize imports and Perform code analysis checkboxes in the commit dialogue.

Testing

The HiveMQ CE project only accepts pull requests that contain unit tests and have sufficient unit test coverage.

Pull Requests

As soon as your code is ready for a pull request, please link the specific issue that you want to resolve. Once the continuous integration is successful and at least one member of the HiveMQ Development Team has approved the changes, you will be asked to rebase and squash before the pull request can be merged.

We greatly appreciate your involvement and contribution.