Skip to main content

Contributing

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. If a pull request exists that corresponds to the issue, mention this pull request on the GitHub issue.

Guidelines for Contributing Code, Examples, Documentation​

Code changes are submitted via a pull request (PR). When submitting a PR use the following guidelines:

Code changes are submitted via a pull request (PR). When submitting a PR use the following guidelines:

  • Follow the style guide below
  • Add/update documentation appropriately for the change you are making.
  • Non-trivial changes should include unit tests covering the new functionality and potentially integration tests.
  • Bug fixes should include unit tests and/or integration tests proving the issue is fixed.
  • Try to keep pull requests short and submit separate ones for unrelated features.
  • Keep formatting changes in separate commits to make code reviews easier and distinguish them from actual code changes.

Code Style​

We have a checkstyle file with code style rules. Please adhere to that. Build will fail if your code has any violations.

To generate a report for violations, run below command: 

mvn site

This will generate a checkstyle.html file.

Some conventions worth mentioning are:

  • All import statements are listed explicitly. The wildcard (*) is not used in imports.
  • Imports are groups as follows:
    import static packages

    <blank line>

    import all packages (lexographically ordered)
  • Javadoc is highly recommended and often required during reviews in interfaces and public or protected classes and methods.

Titles and changelogs​

The title of a pull request is used as an entry on the release notes (aka changelogs) of the connector in every release.

For this reason, please use a brief but descriptive title for your pull request. If GitHub shortens your pull request title when you issue the pull request adding the excessive part to the pull request description, make sure that you correct the title before or after you issue the pull request.

If the fix is a minor fix you are encouraged to use the tag MINOR: followed by your pull request title. You may link the corresponding issue to the description of your pull request but adding it to the title will not be useful during changelog generation.

When reverting a previous commit, use the prefix Revert on the pull request title (automatically added by GitHub when a pull request is created to revert an existing commit).

Tests​

Every pull request should contain a sufficient amount of tests that assess your suggested code changes. It’s highly recommended that you also check the code coverage of the production code you are adding to make sure that your changes are covered sufficiently by the test code.

Description​

Including a good description when you issue your pull requests helps significantly with reviews. Feel free to follow the template that is when issuing a pull request and mention how your changes are tested.

Github Workflow​

  1. Fork the connector repository into your GitHub account: https://github.com/CoffeeBeansLabs/kafka-connect-azure-blob-storage/fork

  2. Clone your fork of the GitHub repository, replacing <username> with your GitHub username.

    Use ssh (recommended):

    git clone git@github.com:<username>/kafka-connect-azure-blob-storage.git

    Or https:

    git clone https://github.com/<username>/kafka-connect-azure-blob-storage.git

  3. Add a remote to keep up with upstream changes.

    git remote add upstream https://github.com/CoffeeBeansLabs/kafka-connect-azure-blob-storage

    If you already have a copy, fetch upstream changes.

    git fetch upstream

    or

    git remote update

  4. Create a feature branch to work in.

    git checkout -b feature-xyz upstream/master

  5. Work in your feature branch.

    git commit -a --verbose

  6. Periodically rebase your changes

    git pull --rebase

  7. 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 s (squash) or f (fixup) to merge extraneous commits.

  8. Submit a pull-request

    git push origin feature-xyz

    Go to your fork main page

    https://github.com/<username>/kafka-connect-azure-blob-storage.git

    If you recently pushed your changes GitHub will automatically pop up a Compare & pull request button for any branches you recently pushed to. If you click that button it will automatically offer you to submit your pull-request to the CoffeeBeansLabs connector repository.

    • Give your pull-request a meaningful title as described above.
    • In the description, explain your changes and the problem they are solving.

  9. 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-xyz

    --force may be necessary to overwrite your existing pull request in case your commit history was changed when performing the rebase.

    Note: Be careful when using --force since you may lose data if you are not careful.

    git push origin --force feature-xyz

Useful Resources for Developers​

  1. Connector Developer Guide: https://docs.confluent.io/platform/current/connect/devguide.html
  2. A Guide to the Confluent Verified Integrations Program: https://www.confluent.io/blog/guide-to-confluent-verified-integrations-program/
  3. Verification Guide for Confluent Platform Integrations: https://cdn.confluent.io/wp-content/uploads/Verification-Guide-Confluent-Platform-Connectors-Integrations.pdf
  4. From Zero to Hero with Kafka Connect: https://www.confluent.io/kafka-summit-lon19/from-zero-to-hero-with-kafka-connect/
  5. 4 Steps to Creating Apache Kafka Connectors with the Kafka Connect API: https://www.confluent.io/blog/create-dynamic-kafka-connect-source-connectors/
  6. How to Write a Connector for Kafka Connect – Deep Dive into Configuration Handling: https://www.confluent.io/blog/write-a-kafka-connect-connector-with-configuration-handling/