Welcome to the HiveMQ Community! Glad to see your interest in contributing to MQTT CLI. Please checkout our Contribution Guide to make sure your contribution will be accepted by the HiveMQ team.
For information on how the HiveMQ Community is organized and how contributions will be accepted please have a look at our HiveMQ Community Repo.
We recommend to develop your changes by using IntelliJ IDEA. Therefore, the following guide will focus on creating your changes using IntelliJ.
Furthermore, the following is needed to make your development efforts as smoothly as possible:
- A Java 11 JDK (for example Azul Zulu JDK)
- Docker
- The following steps will setup a triangle workflow, which will enable you to easily create, update and get your changes into the master branch
- Fork the repository by clicking "Fork" on the main project page (A fork will be created under https://github.com/yourgithubname/mqtt-cli.git)
- Clone your fork via IntelliJ by going to File > New > New Project from Version Control OR by using the
command
git clone https://github.com/yourgithubname/mqtt-cli.git
- Complete the triangle workflow setup by adding
https://github.com/hivemq/mqtt-cli.git
as a remote named upstream via IntelliJ by going to Git > Manage Remotes > + OR by using the commandgit remote add upstream https://github.com/hivemq/mqtt-cli.git
- Decide on your branch name:
- Branch types: feature, bugfix, improvement, cleanup (same as the label of a corresponding GitHub Issue)
- Starting with type:
feature/
,bugfix/
,improvement/
,cleanup/
- + task: lower case, spaces replaced with
-
- Create your branch by using IntelliJ's branch functionality at the bottom of the IDE (upstream/master > New Branch
from 'upstream/master') OR by using the command
git checkout -b branch-type/your-branch-name
- Implement your changes under
src/main/java
- You can use the existing code as a guide
- The project uses Nullability annotations to avoid NullPointerExceptions:
@NotNull
,@Nullable
. Every non-primitive parameter, return type and field should be annotated with one of them.
- There are three types of tests in mqtt-cli:
- Unit Tests =>
src/main/test
- Integration Tests =>
src/main/integrationTest
- System Tests =>
src/main/systemTest
- Unit Tests =>
- Your code changes must be unit-tested
- Depending on your changes an integration test should be written
- Depending on your changes or if you are developing a new feature a system test should be written
- See Building from source for instructions on how to build mqtt-cli
- Before proceeding to the next step, please make sure that your changes build and all tests succeed
- Tip: After building mqtt-cli you can execute the cli by using the generated jar
file
java -jar build/libs/mqtt-cli-<version>.jar
(you can also just build this jar by using./gradlew shadowJar
) - Tip: To quickly test your changes manually you can directly execute commands from your IDE by going to Run > Edit Configurations... and adding your cli arguments
- Before committing execute
./gradlew licenseFormat
to add license headers to each file - Reformat each changed file using the .editorconfig settings of the project
- Commit your changes directly from IntelliJ by pressing
Command
+K
OR via the commandgit commit -m "your commit mesage"
- Commits should be as atomic as possible
- Commit messages should describe the changes clearly
- Commit messages should start with a capital letter for consistency
- Commit messages should avoid exceeding the line length limit,
- Instead, use multiple lines, each describing one specific change
- Push your changes to the remote
origin
by pressingCommand
+Shift
+K
OR via the commandgit push origin branch-type/branch-name
- By contributing your code, you agree to license your contribution under the terms of the Apache License, Version 2.0
- Go to your GitHub fork under https://github.com/yourgithubname/mqtt-cli.git
- Go to the Pull Requests tab
- Press the New Pull Request button
- Choose your branch and click Create Pull Request
- We will now try to review your submitted code as fast as possible
- Furthermore, our CI will run tests against the changes
- To address requested changes during code review or if you need to address failing CI tests, simply push your changes to your remote as described above
- You may need to rebase your branch if you haven't worked on it for some time - To do so simply go to the Git
branch > upstream master > Rebase 'your-branch' onto 'upstream/master' OR via the
command
git rebase upstream/master
- As soon as the Code Reviewer has approved your Pull Request Merge your PR by clicking Rebase and Merge
We truly appreciate and value your time and work. ❤️