Thanks for helping us to make KSQL even better!
If you have any questions about how to contribute, either create a GH issue or ask your question in the #ksql channel in our public Confluent Community Slack (account registration is free and self-service).
Building and running KSQL locally
To build and run KSQL locally, run the following commands:
$ mvn clean package -DskipTests $ ./bin/ksql-server-start -daemon config/ksql-server.properties $ ./bin/ksql
This will start the KSQL server in the background and the KSQL CLI in the foreground.
If you would rather have the KSQL server logs spool to the console, then
-daemon switch, and start the CLI in a second console.
Testing changes locally
To build and test changes locally, run the following commands:
$ mvn clean install checkstyle:check integration-test
How to Contribute
Reporting Bugs and Issues
Report bugs and issues by creating a new GitHub issue. Prior to creating an issue, please search through existing issues so that you are not creating duplicate ones.
Guidelines for Contributing Code, Examples, Documentation
When submitting a pull request (PR), use the following guidelines:
- Follow the style guide below
- Add/update documentation appropriately for the change you are making.
- If you are introducing a new feature you may want to first submit your idea by creating a new GitHub issue to solicit feedback.
- Non-trivial changes should include unit tests covering the new functionality and potentially function tests.
- Bug fixes should include a unit test or integration test reproducing the issue and potentially function tests.
- Try to keep pull requests short and submit separate ones for unrelated features, but feel free to combine simple bugfixes/tests into one pull request.
- Keep the number of commits small and combine commits for related changes.
- Each commit should compile on its own and ideally pass tests.
- Keep formatting changes in separate commits to make code reviews easier and distinguish them from actual code changes.
The project uses [GoogeStyle][https://google.github.io/styleguide/javaguide.html] code formating. You can install this code style into your IDE to make things more automatic:
- [Intellij code style xml file][https://github.com/google/styleguide/blob/gh-pages/intellij-java-google-style.xml]
- [Eclipse code style xml file][https://github.com/google/styleguide/blob/gh-pages/eclipse-java-google-style.xml]
In addition, the project also uses
final fields, parameters and local variables for new code submissions.
IntelliJ's code generation can be configured to do this automatically:
Preferences -> Code Style -> Java -> Code Generation Tick: - Make generated local variables final - Make generated parameters final
Static code analysis
The project build runs checkstyle and findbugs as part of the build.
You can set up IntelliJ for CheckStyle. First install the CheckStyle IDEA plugin, then:
IntelliJ->Preferences→Other Settings→CheckStyle - Add a new configurations file using the '+' button: Description: Confluent Checks URL: https://raw.githubusercontent.com/confluentinc/common/master/build-tools/src/main/resources/checkstyle/checkstyle.xml Ignore invalid certs: true - (Optional) Make the new configuration active. - Highlight the newly added 'Confluent Checks' and click the edit button (pencil icon). - Set properties to match the `checkstyle/checkstyle.properties` file in the repo.
'Confluent Checks' will now be available in the CheckStyle tool window in the IDE and will auto-highlight issues in the code editor.
confluentinc/ksqlrepository into your GitHub account: https://github.com/confluentinc/ksql/fork.
Clone your fork of the GitHub repository, replacing
<username>with your GitHub username.
Use ssh (recommended):
git clone email@example.com:<username>/ksql.git
git clone https://github.com/<username>/ksql.git
Add a remote to keep up with upstream changes.
git remote add upstream https://github.com/confluentinc/ksql.git
If you already have a copy, fetch upstream changes.
git fetch upstream
Create a feature branch to work in.
git checkout -b feature-xxx remotes/upstream/master
Work in your feature branch.
git commit -a
Periodically rebase your changes
git pull --rebase
When done, combine ("squash") related commits into a single one
git rebase -i upstream/master
This will open your editor and allow you to re-order commits and merge them:
- Re-order the lines to change commit order (to the extent possible without creating conflicts)
- Prefix commits using
f(fixup) to merge extraneous commits.
Submit a pull-request
git push origin feature-xxx
Go to your fork main page
If you recently pushed your changes GitHub will automatically pop up a
Compare & pull requestbutton for any branches you recently pushed to. If you click that button it will automatically offer you to submit your pull-request to the
- Give your pull-request a meaningful title.
- In the description, explain your changes and the problem they are solving.
Addressing code review comments
Repeat steps 5. through 7. to address any code review comments and rebase your changes if necessary.
Push your updated changes to update the pull request
git push origin [--force] feature-xxx
--forcemay be necessary to overwrite your existing pull request in case your commit history was changed when performing the rebase.
Note: Be careful when using
--forcesince you may lose data if you are not careful.
git push origin --force feature-xxx